id,summary,reporter,owner,description,type,status,priority,milestone,component,resolution,keywords,cc,branch,branch_author,launchpad_bug
5645,Document the correct way to deprecate a function in Twisted,exarkun,,"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,new,normal,,core,,documentation,,,,