# What is Deprecation Policy?

A deprecation policy is a published commitment about how a software product handles features being phased out: how a feature gets marked deprecated, how long it remains supported, what notice consumers receive, and when it's finally removed. Strong policies (e.g., 12-month sunset window with announcements in every interim release) build trust with developers integrating against your APIs. Absent policies — where features just disappear in a release — drive churn from teams that can't predict your roadmap.


## Example

Stripe's API deprecation policy guarantees a minimum 12-month sunset
window: when a feature is marked deprecated, it stays supported for
at least a year before removal, and every release in that window
explicitly mentions it. AWS publishes a similar policy for SDK
versions and individual service features. At the open-source end,
semver-aware libraries typically remove deprecated APIs only at major
version bumps and document them in release notes for both the
deprecation release and the removal release.

## Why it matters

Integrators building against your product are making a bet that your
surface area won't shift under them. A published deprecation policy
is how you make that bet explicit and predictable. Without one,
every release is a risk for their integration — they don't know
whether something they depend on will be gone next quarter. With
one, they can plan: the deprecated feature is on a known clock and
they get the lead time to migrate.

## More context

The components of a usable deprecation policy:

**1. A clear marker for "deprecated."** The feature is still functional, but its days are numbered. In API responses this often appears as a `Deprecation` HTTP header or a field in the response body. In SDKs and libraries it's a `@deprecated` annotation, a compiler warning, or a runtime console log.

**2. A minimum sunset window.** How long after the deprecation announcement does the feature remain functional? 12 months is the standard for production-grade APIs. Shorter windows (3-6 months) are acceptable for newer or beta features that explicitly opted out of long-term stability guarantees. Indefinite windows are a non-answer.

**3. Communication in every release during the window.** A feature marked deprecated in release v2.3.0 and never mentioned again until removal in v3.0.0 will be missed. Every release in between should list it under "Deprecated" so integrators have repeated exposure.

**4. Migration guidance at the deprecation moment.** "Use the new `/v2/foo` endpoint instead" should appear in the same release notes entry that announces the deprecation. Migration guidance discovered six months later is harder to retrofit.

**5. The removal announcement is its own release-notes section.** Removing the feature isn't a "minor improvement" — it's a [breaking change](/glossary/breaking-change/) and should appear in the dedicated breaking-changes section of the release notes for the removal release.

For developer-tool products specifically, the published deprecation policy is one of the highest-trust signals you can offer. It tells potential customers: this team thinks about you. Teams that ship without one often discover the cost only after they break someone's production integration with no notice — by which point the customer is already evaluating alternatives.

For the practical "how to write the deprecation announcement itself" piece, see the [release notes guide](/blog/how-to-write-release-notes/).

## Related terms

- [Breaking Change](/glossary/breaking-change/)
- [Conventional Commits](/glossary/conventional-commits/)
- [Release Notes](/glossary/release-notes/)
- [Changelog](/glossary/changelog/)

Deeper guide: [How to write release notes users actually read](/blog/how-to-write-release-notes/)

Category: Quality & Trust
Last reviewed: 2026-05-28