Deprecating an API
Deprecating and removing are two changes, and only the second one breaks
anyone. This skill produces what yagni and refactor-architecture wait
for before they delete: a record with the measured remaining use and the
owner's remove row (removal approved). It never removes an interface in
the change that marks it, and never without that row.
When to use
- A function, method, class, endpoint, response field, CLI flag, config key, event, or message type that other code, other repositories, or other teams call is being removed, replaced, renamed, or given a sunset date.
- A metric name, label, or log field that a dashboard or alert reads is being renamed or removed; its readers are the callers, and the skip below does not apply to it.
- Skip when every caller is in this repository and a search finds all
of them: change the callers and the interface in one change under
test-driven-development. - Skip a stored data shape (a column, field, or document shape):
changing-a-live-schemaowns that; hand off and say so. An interface that returns the stored shape stays here.
Step 1: Measure the old path first
Open assets/deprecation-record.md before the actions below; they fill its
header, Callers, and Use sections.
- Record the interface, its owner, and every caller a search finds. A search is a lower bound: external consumers, other repositories, generated clients, reflection and dynamic dispatch, and old app versions that never update do not show in it.
- If the old path has no per-caller count (a metric or log line carrying the caller's identity: client id, package version, user agent, or call site), add one and ship it before anything else. The removal date is set from what it reports, not from the search.
- If use cannot be measured, write
unknownin the Use section. Never write zero for a path nothing counts.
Step 2: Ship the replacement first
- The replacement exists, is tested, and is documented before the old interface is marked; fill the record's Interface section as it ships. If there is no replacement, say so in the record; the signal in Step 3 then names the end of support, not a replacement.
- Where the old path can call the new one, make it do so, so the two cannot drift apart.
- REQUIRED SUB-SKILL: invoke
test-driven-developmentfor the replacement. The tests of the old path stay green and in place until the removal change; they are preserved behaviour, not dead tests.
Step 3: Mark it and set the date
The signal goes where the caller will see it, through the mechanism the language or protocol defines; a changelog line or a document alone is not a signal:
- a library: the language's deprecation marker, with the replacement and the sunset date in its message;
- an HTTP endpoint or response field: the
DeprecationandSunsetresponse headers, and aLinkwithrel="deprecation"to the migration notes; - a CLI flag or config key: a warning on the error stream when the flag or key is read;
- an event or message type: a warning logged by the producer where it is built, since consumers cannot see a marker;
- an interface clients are generated from (an API schema or interface definition): the schema's own deprecation field, since a marker in the handler never reaches a generated client;
- a metric name, label, or log field: emit both the old and the new name until the sunset date, and name the old one in the record's Signal section, since a dashboard or alert cannot see a marker.
Read
references/signal-mechanics.mdbefore writing an HTTP header, a schema deprecation, or a Python, Java, TypeScript, or Go marker: each has a form that looks right and signals nothing.A runtime warning fires once per process, or once per caller identity, never once per call: a warning on every call floods the logs and gets silenced along with the signal.
The sunset date belongs to the owner. Use the project's deprecation policy if one exists; if none does, ask and end the turn:
Sunset date for {{interface}}: replacement {{name}} shipped in {{version or revision}}; measured use {{n callers per period, or unknown}}; known callers {{list}}. 1. {{the project's usual notice period, or one release cycle}} from the deprecation release 2. Another date: print it Recommendation: {{option}} — {{one sentence}}.Record the date and its source, the policy or the answer, as the sunset-date row in the ledger beside the record.
Ship the deprecation as its own change through the ordinary chain. It removes nothing. If a caller is in another team's hands, the record's Callers table names who was told and how.
Step 4: Watch, then decide the removal
After the sunset date, read the per-caller count over a span that covers every caller's cycle (a monthly job calls once a month) and update the Use section with the current number and who is behind it.
If use is above zero or
unknownand the system can switch the old path off and on, ask the owner for one brownout and end the turn: the old path off for a short stated window, back on, then read who complained or errored. Run it only on their yes; record the answer and the result.Removal is the point of no return. Put it to the owner with the measured use and who breaks, and end the turn;
clarifying-intentowns what closes it:Remove {{interface}}: sunset {{date}} passed; measured use {{n per period, or unknown}} from {{callers, or "cannot be identified"}}; brownout {{result, or not run}}. Removing it breaks {{who}}; they recover by {{replacement}}. 1. Remove: ship the removal change 2. Hold until {{condition}}: keep the old path and the signal Recommendation: {{option}} — {{one sentence}}.Use that never reaches zero is the owner's call, never the agent's. Record the answer as a row in the ledger beside the record; without a row, the removal does not ship.
The removal is its own change through the ordinary chain, built under
test-driven-development: the old path's tests go in the same change as the old path, not before. REQUIRED SUB-SKILL: at the release step, invokerelease-readinessand hand it the record.Removal approved is this record plus the owner's
removerow in the ledger: the removal change may proceed on it, and a skill that asks for a completed deprecation before it deletes accepts it. The deprecation is complete only when the record's Status isremovedand names the ledger row; until then, any other ask gets "in progress" and this record's path.
Hard stops
- Removing the interface in the same change that marks it deprecated.
- Marking an interface deprecated before its replacement ships, when one is planned.
- Shipping a removal without a ledger row from the owner, even when the measured use is zero.
- Writing zero for use that nothing counts.
Gotchas
- Where the build treats warnings as errors, the marker turns callers and the old path's own tests red. Exempt those tests and each known call site by name; never switch the warning class off project-wide or delete the tests — shows when the deprecation change itself fails CI.