---
title: "Deprecate in a minor release before · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/libraries-and-sdks/deprecation-policy
id: ENG-52
level: Recommended
updated: 2026-10-22
tokens: 861
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Deprecate in a minor release before removing in a major one

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: ENG-52
- Level: Recommended
- Chapter: [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md)
- Rule: Publish a deprecation policy. Mark a feature deprecated in a minor release, with a warning at run time and in the docs. Remove it only in a later major release.
- Check: Every feature removed in a major release appears as deprecated in the changelog of an earlier minor release. A test calls each deprecated function and asserts that it emits a deprecation warning.
- How: The Semantic Versioning FAQ asks for at least one minor release that contains the deprecation before the removal. State in the policy how long a deprecated feature stays, such as 6 months or one major version. The warning names the replacement and the version that removes the old feature. Users who follow [Turn deprecation warnings into test failures](https://agentwranglers.se/playbook/testing/test-quality/deprecations-fail-tests.md) then find every use before the upgrade. HTTP APIs announce the same with headers, as [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { deprecate } from 'node:util';

export const sendInvoice = deprecate(
  (invoice) => deliverInvoice(invoice),
  'sendInvoice() is deprecated and is removed in 4.0. Use deliverInvoice().',
  'INVOICES_DEP001',
);
```

### Python example

```python
from warnings import deprecated  # Python 3.13 and later

@deprecated("send_invoice() is deprecated and is removed in 4.0. Use deliver_invoice().")
def send_invoice(invoice):
    return deliver_invoice(invoice)
```

## Sources

- [Semantic Versioning 2.0.0, FAQ](https://semver.org/#how-should-i-handle-deprecating-functionality)

## Related rules

- TST-52 [Turn deprecation warnings into test failures](https://agentwranglers.se/playbook/testing/test-quality/deprecations-fail-tests.md) in Testing
- API-29 [Announce deprecation and sunset in headers](https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/engineering/libraries-and-sdks/deprecation-policy">Agent Wranglers engineering playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Check every release against the public API](https://agentwranglers.se/playbook/engineering/libraries-and-sdks/semver-check.md)
- Next: [Publish a support matrix](https://agentwranglers.se/playbook/engineering/libraries-and-sdks/support-matrix.md)
- [Libraries and SDKs](https://agentwranglers.se/playbook/engineering/libraries-and-sdks.md)