id summary reporter owner description type status priority milestone component resolution keywords cc branch branch_author
5645 Document the correct way to deprecate a function in Twisted exarkun adiroiban "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.
" enhancement closed normal core fixed documentation branches/deprecation-note-list-5645 adiroiban