Ticket #5645 enhancement new
Document the correct way to deprecate a function in Twisted
|Reported by:||exarkun||Owned by:|
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.
Note: See TracTickets for help on using tickets.