Deprecating a function in a library: warn, document the replacement, remove on schedule

Goal

Remove or change a public function, class or option in a library without breaking users between consecutive releases, and without carrying the old path forever. This is the library-side counterpart of deprecating an HTTP endpoint (linked), with warnings and version policy in place of headers.

Prerequisites

A definition of what is public. PEP 387 counts names, argument positions and types, return values and raised exceptions as public, and excludes underscore-prefixed names and anything documented as private; an undocumented name is not automatically private. A written cadence policy, because the removal date is expressed in releases.

Steps

1. Ship the replacement first, in a release that still supports the old path unchanged, so that migration is one step.
2. Mark the old path in the same or the next release: a runtime warning of the deprecation category, a note in the reference documentation with the version of deprecation and the replacement, and an entry under a Deprecated heading in the changelog.
3. Fix the removal release by policy rather than case by case. PEP 387 states that an incompatible change must go through the deprecation process, that the yearly cadence means at least two years between warning and removal, and (since a 2025 change) that five years is preferred; Django's policy keeps a deprecated feature working through all releases of the current major series and removes it in the next major, or one release later, so that at least two feature releases separate warning and removal. A small project can adopt "removed no earlier than the second feature release after the warning".
4. Make the warning visible where it counts. Python's default filter ignores DeprecationWarning except when triggered directly by code in __main__; the documentation advises test runners to display all warnings for the code under test. Run the library's own test suite with warnings turned into errors so that internal uses of the old path surface first.
5. Prefer a soft deprecation when the old path is safe to keep: PEP 387 describes it as documented, tested, no longer developed and without a scheduled removal or a warning.
6. Remove in the announced release, list it under Removed in the changelog, and bump the version according to the versioning policy (a major version under Semantic Versioning).

Expected result

Users see one warning per old call site pointing to the replacement and know the release in which it disappears; the library carries each shim for a bounded number of releases.

Limits and test basis

Policies are quoted from the cited Python and Django documents; a project with a different cadence must translate "two releases" into its own time. No migration outcome is measured.