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.

[tom.prince]

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

[tom.prince]

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

[tom.prince]

#3266 is also related.