Semantic Versioning says to do two things when you deprecate part of your public API: update the documentation, and issue a new minor release with the deprecation in place. At least one minor release containing the deprecation should ship before the functionality is removed in a major release, so users can move over gradually.
The rule
The Semantic Versioning site calls deprecation a normal part of software development, often required to make progress. Its guidance is short. Update your documentation to tell users about the change, and issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release, there should be at least one minor release that contains the deprecation, so users can transition to the new API smoothly.
The specification backs this up. A minor version must be incremented if any public API functionality is marked as deprecated, and a major version must be incremented if backward incompatible changes are introduced. Patch versions are for backward compatible bug fixes.
| Change | Version part to raise |
|---|---|
| Bug fix, no API change | Patch |
| New compatible feature, or any deprecation | Minor |
| Removal or incompatible change | Major |
Why it matters for security
Deprecation is often how a library retires an unsafe default or a risky function. If you remove it in one step, users who do not read release notes get a broken build and may pin to the old version, which keeps the unsafe code in use. If you deprecate first and warn loudly, most users move before the removal.
What a good deprecation notice contains
- The name of the function or option affected.
- The reason, including any security reason, in plain words.
- The replacement, with a short example.
- The version in which it was deprecated, and the planned removal version.
- A runtime warning where practical, so the notice reaches people who never read documentation.
- A changelog entry under its own heading, so scanners and humans can find it.
When security forces the issue
SemVer does not forbid a fast change when a vulnerability requires it. If a feature cannot be made safe, say so in the advisory, ship the fix in the lowest affected supported lines, and explain any break. The Django project states a similar exception in its own policy: patch releases are fully compatible unless that is impossible for security reasons or to prevent data loss. Keep exceptions rare, and write down why.
Steps for a maintainer
- Decide the replacement before you announce the deprecation.
- Release the deprecation in a minor version with documentation and a warning.
- Wait at least one minor release, longer if the feature is widely used.
- Announce the removal date in the changelog and repository.
- Remove it in the next major release.
- Link both releases from your security policy if the reason was security.
Quick check
Does a deprecation need a major release?
No. Under SemVer it needs a minor release. The removal needs a major release.
How long should a deprecated feature stay?
SemVer asks for at least one minor release containing the deprecation before removal. Longer is kinder for widely used features.
Can I remove an unsafe feature in a patch release?
SemVer reserves patch releases for backward compatible fixes. If you must break compatibility for security, explain it clearly in the advisory.
How Safeguard helps
Safeguard's SBOM and dependency scanning show which upstream versions you depend on, and reachability analysis helps you decide which advisories matter for your code. Compliance and evidence automation can record how you handled each one. Autonomous remediation can open fix pull requests; it is off by default and every category starts on Manual. You can run the free scan on a manifest to see where you stand.
Sources
- Semantic Versioning 2.0.0, semver.org: version rules and the deprecation guidance in the FAQ. Fetched 19 October 2026.
- Django Software Foundation, Download Django: patch release compatibility statement. Fetched 19 October 2026.
Last reviewed: 19 October 2026.
