Migration and release notes

Migration Guides & Release Notes

Help developers and operators understand what changed between versions, who is affected, and the exact steps required to upgrade—and roll back if needed—without surprises.

1. Lead with impact and compatibility

• Who is affected: state immediately which users, integrations, environments or configurations are touched by the change.
• Breaking changes first: highlight removed or renamed endpoints, changed payload shapes, stricter validation rules, new required environment variables, dropped runtime versions or altered defaults at the top before minor additions.
• Version and environment scope: name the exact version, branch or migration number where the change takes effect.

2. Write concrete before/after migration steps

For every breaking or behavioral change, show:

1. What changed and why: one or two sentences on the old behavior, the new behavior, and the reason.
2. Before and after examples: side-by-side code, configuration or API payload snippets showing the old pattern and its replacement.
3. Ordered upgrade steps: exact sequence of actions—backup, dependency install, configuration update, database migration, build, service restart—so nothing runs out of order.
4. Automatic vs. manual upgrades: distinguish what the runtime migrates automatically on startup (such as schema migrations or one-time setting upgrades) from what a person must change manually.

3. Data safety, rollout order and rollback

• State whether a database migration or data upgrade is additive and backward-compatible, or destructive/irreversible.
• Document how to verify the upgrade succeeded (health check, migration table, test command, expected log line).
• Document the rollback path: how to revert the code, configuration or data safely, and any point of no return (such as a destructive column drop or external side effect).

4. Keep release notes factual and scannable

• Group entries by impact: Breaking Changes, Added, Changed, Deprecated, Fixed, Security.
• Describe user- and developer-visible behavior rather than internal file shuffles or commit noise.
• Never list planned future work as part of a shipped release.

Before you finish

• Breaking changes, new requirements and altered defaults are surfaced first.
• Before/after examples match the old and new code, schemas and configuration keys.
• Automatic startup migrations vs. manual operator steps are clearly separated.
• Verification and rollback steps (including any irreversible step) are documented.