Deprecation window
A deprecation window is the period between announcing that a feature will be removed and actually removing it — typically 3-12 months for SaaS APIs, longer for libraries. The window gives consumers time to migrate without forcing emergency work, and gives the maintainer cover to remove cleanly when the window expires.
Healthy deprecation has three components: clear announcement (changelog, dashboard banner, deprecation header in API responses), migration documentation (specifically, the working alternative and a code example), and observable usage signal (the maintainer can see whether consumers are still using the deprecated path). Without all three, deprecation tends to either drag on indefinitely (consumers don't migrate; maintainer doesn't remove) or break consumers (maintainer removes; nobody knew). Stripe's deprecation discipline (12 months minimum, per-API-version, dashboard counter showing per-merchant usage) is the gold standard for SaaS APIs.
Related terms
- Breaking change
A breaking change is any change to a published interface (API endpoint, library function signature, CLI flag, configuration key) that requires consumer code or configuration changes to keep working.
- Semantic versioning (semver)
Semantic versioning is the package-versioning convention MAJOR.
- Lockfile
A lockfile records the exact resolved version of every package in a dependency tree — direct and transitive — so any subsequent install reproduces the same versions.