Opened 3 years ago

Last modified 23 months ago

#5645 enhancement new

Document the correct way to deprecate a function in Twisted

Reported by: exarkun Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Branch:
Author: Launchpad Bug:

Description

We have a pretty strict process for deprecations. It's simple, but the steps all need to be followed exactly:

  • Do not change the function's behavior as part of this process
  • Cause usage of the function to emit a DeprecationWarning
    • either call warnings.warn
    • or use one of the APIs in twisted.python.deprecate
  • The warning text must include the version of Twisted in which the function is first deprecated (which will always be a version in the future)
  • The warning text should recommend a replacement, if one exists
  • The warning must "point to" the code which called the function. For example, in the normal case, this means stacklevel=2 passed to warnings.warn.
  • There must be a unit test which verifies these things.
    • Unit tests can use TestCase.flushWarnings or callDeprecated or one of the other helpers.
  • A .removal news fragment must be added.

Maybe I forgot some things, too.

Change History (3)

comment:1 Changed 23 months ago by tom.prince

  • Tests of the deprecated function must be left, and appropriate .suppress attribute added to avoid emitting the DeprecationWarning for them.

comment:2 Changed 23 months ago by tom.prince

#6266 is relevant for making remaining tests not emit deprecation warnings.

comment:3 Changed 23 months ago by tom.prince

#3266 is also related.

Note: See TracTickets for help on using tickets.