Writing Migration Guides

Reference: supabase-flutter's MIGRATION.md. It gets this right — read a section or two before writing your own if you want the tone.

Step 1: Confirm it needs an entry

Every breaking change needs one: a renamed or retyped public symbol, a changed default, a changed error type, an event that fires differently, anything that a feat!:/fix!: commit or BREAKING CHANGE: footer would announce. A deprecation alone does not — that gets an @available(*, deprecated, ...) message instead (see Step 5).

Completion criterion: you can name the exact symbol or behavior that changed and why a caller would need to touch their code because of it.

Step 2: Find the file, don't create a new one

supabase-swift keeps a single migration guide per upcoming major version, at the repo root, covering every module: