LI
Backward Compatibility
Semver compliance, deprecation workflow, and breaking change management for libraries
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Follow semantic versioning strictly: breaking changes bump major, new features bump minor, bug fixes bump patch. Never introduce breaking changes in a minor version.
- Deprecate before removing: mark APIs as deprecated for at least one major version cycle before removal. Include the migration path in the deprecation message.
- Treat any change that could break a consumer as breaking: removing fields, changing return types, renaming exports, altering default behavior.
- Maintain a CHANGELOG.md that describes every change with the version, date, and category (Added, Changed, Deprecated, Removed, Fixed).
- Add runtime deprecation warnings that print once per call site: "Warning: foo() is deprecated, use bar() instead. Will be removed in v3.0."
- Write codemods or migration scripts for major version transitions. Automated migration reduces the friction of upgrading.
- Run backward-compatibility tests in CI: install the previous minor version's test suite and run it against the current code. If tests fail, you have a breaking change.
- Document all breaking changes in a dedicated MIGRATION.md for each major version. Include before/after code examples for every change.
- Use feature flags for gradual rollout of behavioral changes. Let users opt in to new behavior before it becomes the default in the next major version.
- Publish release candidates (1.0.0-rc.1) for major versions. Give consumers 2-4 weeks to test before the final release.