How to write deprecation notices
Communicate a replacement and removal policy before compatibility ends.
01Separate deprecated from removed
Deprecated means still available but discouraged; removed means unavailable. Give the first deprecated version and the planned removal version or date only when committed. If no date is decided, say so explicitly.
02Offer a usable replacement
Name the replacement and describe differences in inputs, outputs and permissions. If no replacement exists, explain the supported alternative workflow rather than sending readers to a generic documentation homepage.
03Make the deadline operational
Use an unambiguous date and timezone for service shutdowns. Explain whether the cutoff affects existing integrations, new configuration or both. Notify the owners of affected installations through appropriate channels, not just a passive archive.
04Keep notices discoverable across versions
Repeat outstanding deprecations in upgrade documentation and update the notice when the plan changes. LogPulse deprecation records can carry the item, replacement, removal version and note; do not invent a removal version merely to fill a field.
Before and after
Too vague
Legacy exports are going away soon.
Specific and actionable
Deprecated in 1.8.0: exportCsvLegacy(). Use exportCsv({format: "standard"}); the replacement quotes embedded newlines. Removal is planned for 2.0.0. Add a multiline-cell fixture before switching.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Distinguish deprecation from removal
- Name a working replacement
- Verify the deadline or say it is undecided
- Test edge cases in the replacement
- Link a migration contact
Common questions
Keep reading
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.