A deprecation notice gets noticed when it says four things in order: what is going away, on what date, who is affected, and what to do instead. It gets noticed even more when it is repeated on dates set in advance, because a first message is only read by the people who read everything.
Nearly every missed notice failed the same way: well written, published once, buried three weeks later. The flaw is not clarity. It is reach.
Before and after: one removal, two notices
Take an illustrative removal in a fictional product: the /v1/export endpoint will be removed in favour of /v2/export. Here is the notice many teams write.
Before. We are evolving our export API. The old endpoint will be removed soon. See the documentation to learn more.
Nothing in it is wrong. Nothing in it is usable either: which endpoint, when, for whom, replaced by what? The reader learns there is a subject and cannot tell whether it is theirs.
After.
/v1/exportwill be removed on June 30. If your integration calls it, it will stop working that day. Replacement:/v2/export, same authentication, dates are returned in ISO format. To check whether you are affected, search your calls for/v1/export. No action needed if you have never called this endpoint.
The difference is three additions: a date, a test for recognising yourself, and an exit for those who are not concerned. The second notice is two lines longer and saves dozens of messages to support.
Look at the last sentence. Saying who the notice is not for is as useful as saying who it is for: it frees the majority's attention and concentrates the affected minority's.
The reminder schedule
A single notice cannot cover the length of a removal. A schedule can, if it is fixed on announcement day and kept. Here is a frame, to adjust to your own delay.
- Announcement, three months out. The full notice above. Published in the changelog, in the release notes, and sent directly to those whose calls are known.
- Reminder, six weeks out. The same four elements, plus the state: "N calls to
/v1/exportremain on your keys." That number comes from your logs, not from an estimate. - Targeted reminder, two weeks out. Only to those still calling the old endpoint. Everyone else hears nothing: they migrated or were never concerned.
- The day itself. Removal, then a changelog entry the same day. A customer arriving after the fact should find a page that explains the error they just received.
What matters is that the dates are written into the first message. A removal whose schedule reveals itself along the way looks arbitrary; a removal whose reminders were announced looks like a process.
On the API side, a Sunset header (RFC 8594) on responses from the old endpoint carries the same date into the client's code. It is a complement, not a replacement: nobody reads response headers in production until an alert puts them in front of them.
The objection: "our changelog already says so"
True, and necessary. A changelog is the register where the notice must appear, dated and public, and we cover why it serves integrators first. But a register is consulted; it does not impose itself. Those who read it every week did not need the notice; those who needed it do not open it.
A deprecation notice is therefore a message that goes to the reader, with a register behind it as proof. They complement each other: the register for evidence, the message for attention.
Where each piece of the notice comes from
The four elements of the notice already exist in the code. What disappears and what replaces it are in the diff. The date is a decision, but it can be checked against the code: is the endpoint really removed on the announced branch? And who is affected can be read in the calls still reaching the old path.
That is where notices written from memory fail: they describe the planned removal, not the real one. If the pull request that deletes /v1/export forgets an alias, the notice is wrong on day one. Catching a breaking change in time is the subject of what changed in the API this week; here, remember that the notice is re-read against the diff before it is published.
DeployIt reads the real code, resynced on every push, and the git history (commits and diffs) through its own MCP servers, and checks the code before it asserts anything. Read-only, revocable at any time. Your docs and your support agents can then answer "is this endpoint still available?" from the state of the code, not from an announcement three months old. The same foundation powers a living help center and an MCP server for agents, in early access / design partner program.
Frequently asked questions
Can you remove faster for a security flaw? Yes, and it is the only case. The notice keeps its four elements, but the date is close and the reason is given in one sentence. A short delay does not excuse the message.
Should a rarely used feature be announced? Yes, with the same structure. "Rarely used" means most customers are not affected, not that the affected few mind less.
What if a customer misses it anyway?
Then the error returned on the day must be the last chance: a message that names the removal, gives the date and points to the replacement. A bare 404 is a second announcement nobody will understand.
What to remember
Four elements in the notice, dated reminders from the first message, targeting based on real calls, and a text re-read against the diff. The rest is care.
DeployIt is free during early access; paid plans arrive in January 2027. The MCP server is in early access / design partner program, and the program is open.
Frequently asked questions
What should a deprecation notice contain?
Four things: what is going away, on what date, who is affected, and what to do instead. A notice that leaves one out forces the reader to write to support to guess it.
How long before the removal should you warn customers?
Long enough for your slowest customer to ship their migration, which depends on their release cycle, not yours. Set the date from that delay, announce it once, then repeat it at regular intervals until the day.
Is one message enough?
No. The first is read by people who read everything, the last by people the removal already breaks. In between, reminders are what reach the teams whose owner was not around at the announcement.
How do you know who is really affected?
Start from the code and the traffic: the calls that still reach the old endpoint. Call logs say who uses it; the diff says what is removed and what replaces it.
Continue reading
Changelog, release notes, "What's new": which one do you need?
One change, three artefacts, three different texts. A worked example shows what each of a changelog, release notes and a "What's new" page keeps, drops and rewrites, and how to pick.
How do you keep developer portal content current between redesigns?
A developer portal ages page by page, not all at once. The way out: know which pages carry a fact from the code, and recompute those from the code instead of rereading them by hand.
How do you keep an engineering team's onboarding docs current?
An onboarding guide goes stale because it describes the code as it was the day it was written. Pull the facts from the code itself, and keep by hand only what no code can say.