How Can a Maintainer Document a Deprecation?
From the earlier reference collection. Read the current software blog.
Make a deprecation actionable by naming the replacement, affected versions, timeline, and compatibility consequences.
Name the old and new interfaces
A deprecation notice should identify exactly what is being deprecated: a command option, API field, file format, library function, or behavior. Give the affected name and explain what users should use instead. “This is deprecated” leaves readers unable to find a migration path. If there is no replacement, explain the supported alternative or why the capability is being removed.
For example, a configuration key named old_endpoint might be replaced by service_url. Show the old and new forms side by side, and state whether the replacement has the same meaning. If the new field changes how values are interpreted, describe the behavioral difference rather than presenting a mechanical rename as sufficient.
Pin versions and dates
State when the deprecation began and which versions still accept the old interface. Use release numbers and dates where they are known. A timeline can distinguish the first warning, the last version expected to support the old form, and the earliest version where removal may occur. Do not publish a deadline as certain if it has not been decided; label it as planned or under review.
A concrete notice might say that version 4.2 began warning on use, version 4.x continues to accept the option, and removal is planned for version 5.0. Those figures are illustrative only; use the project's actual schedule. If downstream packages have different release cycles, explain which project's version numbers control.
Explain compatibility impact
Describe who must act and what will happen if they do not. Could an existing configuration continue working with a warning, fail on the next major release, or produce different output? Tell users whether automated scripts, saved files, or integrations are affected. A deprecation can be low-risk for interactive users and disruptive for unattended jobs that treat warnings as errors.
Offer a migration example with realistic syntax and identify any required steps beyond editing a name. If the old and new interfaces behave differently, include a small input and output example or explain the changed default. Point to a migration guide when the conversion involves several steps.
Keep warnings useful
A warning should identify the deprecated element and, where possible, point to the replacement and removal version. Avoid warning on every operation if the same message becomes noise, but do not hide it where operators can miss an upcoming compatibility break. Document whether warnings go to standard error, logs, or a user interface so people know where to look.
End the notice with a clear action: update the named setting, test against the replacement, and plan before the stated removal boundary. Keep the deprecation record available after removal so maintainers and users can understand why old examples no longer work. Update release notes and reference pages together when the timeline changes.