THE GITHTML FIELD GUIDE
Deprecation notice template with a clear replacement path
A deprecation notice should explain what is discouraged, what still works, what replaces it, and when support changes. Name the affected audience and provide a tested migration path. Distinguish a planned removal from an approved date, and avoid treating a version number as a substitute for clear compatibility guidance.
Define the exact deprecated surface
Be specific about the operation, field, configuration key, or supported environment involved. An illustrative notice might deprecate one export endpoint while leaving the export feature itself supported. State the current behavior so readers understand that deprecation does not necessarily mean immediate failure. Explain the reason in terms useful to the audience, without exposing private discussions or overpromising benefits. Semantic Versioning can communicate compatibility expectations when the project adopts it, but readers still need a plain-language description of what will change.
Provide a migration that can be checked
Show a small before-and-after example using fictional identifiers and explicitly label it illustrative. Then document differences in behavior, not just renamed syntax. For an API replacement, verify authentication, pagination, defaults, and error handling against the actual contract before saying the replacement is equivalent. Link a fuller migration guide when the transition has several steps. Give users a way to determine whether they are affected that does not require sharing secrets or production payloads with the documentation author.
- Affected surface: identify the exact behavior and relevant versions.
- Replacement: explain the supported path and any non-equivalent behavior.
- Timing: distinguish the announcement, support change, and approved removal milestone.
Maintain the notice through the transition
Assign an owner to update the notice when dates, support policy, or replacement readiness change. Preserve prior versions when people may need to understand old releases, but mark historical guidance clearly. If no removal date exists, say so instead of writing soon. Include a support route for migration blockers and explain what evidence makes a report useful. In the HTML version, place the required action and timing before the rationale. A phone reader should not have to scroll through a long justification to discover that their integration needs work.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.