Documentation and consistency for deprecation

[datapythonista]

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.

[jreback]

certainly take a PR on these

1. how to deprecate
2. change DEPRECATED to the directive (directive is correct, just haven’t changed everything)

[datapythonista]

@jreback, couple of questions:

I'll make sure that the deprecation directive is in all cases right after the short description of the docstring, as the numpy docstring convention defines. Or at the start of the docstring if no short summary is present.

I'm adding a version parameter to the pandas.util._decorators.deprecate, so we can know in which methods are deprecated also when using the decorator.

I added the version to all methods (I used the date of the commit where the deprecation was added), and created a script to see all methods deprecated by version. There are some old ones that I think they should removed, but I think it makes more sense to label all them with the version in this pull request, and remove them in a later pull request, so it's easier to spot which methods have been removed. This is the list of deprecated methods in Series, DataFrame and Panel:

0.7.0
	Panel.toLong
	Panel.to_long
0.18.0
	DataFrame.convert_objects
	Panel.convert_objects
	Series.convert_objects
0.19.0
	Series.reshape
0.20.0
	DataFrame.sortlevel
	Series.sortlevel
0.21.0
	DataFrame._get_value
	DataFrame._set_value
	DataFrame.as_blocks
	DataFrame.blocks
	DataFrame.consolidate
	DataFrame.from_csv
	DataFrame.get_value
	DataFrame.select
	DataFrame.set_value
	Panel._get_value
	Panel._set_value
	Panel.as_blocks
	Panel.blocks
	Panel.consolidate
	Panel.get_value
	Panel.select
	Panel.set_value
	Series._get_value
	Series._set_value
	Series.argmax
	Series.argmin
	Series.as_blocks
	Series.blocks
	Series.consolidate
	Series.from_csv
	Series.get_value
	Series.select
	Series.set_value
0.21.1
	DataFrame.as_matrix
	Series.as_matrix
0.21.2
	Series.valid

Does all that sound good to you?