Long enough for customers to see the notice and finish an upgrade cycle. A public model, the Kubernetes deprecation policy, keeps stable API versions through a whole major version, deprecates beta versions after roughly nine months, and allows alpha versions to vanish without notice. Match your window to how slowly your customers move.
What the public policy says
The Kubernetes policy sets minimum lifetimes by maturity.
| Maturity | Rule from the policy |
|---|---|
| GA | May be marked deprecated, but not removed within a major version |
| Beta | Deprecated no more than 9 months or 3 minor releases after introduction, whichever is longer, and no longer served 9 months or 3 minor releases after deprecation, whichever is longer |
| Alpha | May be removed in any release without prior deprecation notice |
It also gives an example of timing: announce and document the deprecation in sync with the following release.
Adapting it for self-hosted customers
Cloud users upgrade often. On-prem customers may wait many months for a maintenance window and a test cycle. Your window should therefore be measured in the time they need to schedule, test and deploy, not in your own release cadence. A rule that counts releases is fair only if your releases are slow enough to give real time.
A simple scheme
- Label every feature as stable, preview or experimental, in the docs and the UI.
- Promise that stable features are not removed within a major version and that a deprecation is announced at least one release before removal.
- For preview features, state a fixed time window, not just a release count.
- Say plainly that experimental features can change without notice, and keep them off by default.
- Put every deprecation in the release notes with a removal version and a replacement.
The security angle
Deprecated features tend to stop receiving fixes before they stop shipping. Say in the policy whether deprecated features still get security fixes until removal. If not, say that too, so customers can plan. An unmaintained feature that is still enabled is an exposure customers should be told about. Also disable risky deprecated features by default once the notice period ends, rather than silently keeping them on.
Common mistakes
Removing something in a patch release. Announcing a deprecation only in a blog post. Leaving no migration path. See semantic versioning for security fixes for how to number the release that removes it.
If you want a second look at what you ship, Safeguard can generate and scan an SBOM and run dependency scanning with reachability analysis, and you can try the free scan.
Quick check
Can I remove a stable feature in a minor release?
The public model above does not allow removing GA features within a major version. Adopt the same rule or state a different one clearly.
Do deprecated features still get security fixes?
Decide and publish the answer. Silence leaves customers guessing.
Sources
Last reviewed: 19 October 2026.
