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