Documentation and consistency for deprecation
If I'm not wrong, there is not documentation on what's the deprecation policy for Pandas, or how to contribute when classes, functions or methods are being deprecated.

There is this short note on the contributing guide: https://pandas.pydata.org/pandas-docs/stable/contributing.html#backwards-compatibility but I think some more information would be useful:
* How to add the deprecation note in the docstring
* How to add the deprecation warning

And not sure where, but in the user documentation, it would be useful to know what's the deprecation policy (e.g. adding a warning when it's marked for deprecation, and function being removed after one minor version).

Also, not sure if there is a reason I don't know, but in the code, it seems to be two different ways of documenting deprecations:
* With the .. deprecated:: docstring directive (e.g. https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.as_blocks.html)
* With upper case DEPRECATED comment (e.g. https://pandas.pydata.org/pandas-docs/version/0.21.1/generated/pandas.DataFrame.select.html)

If this is just because of lack of consistency, it'd be good to unify them (I assume the docstring directive is the right way).

I'm happy to contribute a pull request once someone can clarify if I'm right, and what's the deprecation policy.