Agent Wranglers

ENG-52Recommended

Deprecate in a minor release before removing in a major one

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.

By Agent Wranglers. Updated .

How to do it

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 then find every use before the upgrade. HTTP APIs announce the same with headers, as Announce deprecation and sunset in headers says.

Examples

JavaScript example

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

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)

How to 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.

Sources

For agents: this playbook is free to use under CC 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.