PDEP-17: Backwards compatibility and deprecation policy
cc @pandas-dev/pandas-core @pandas-dev/pandas-triage 

An implementation of the `PandasDeprecationWarning` variable mentioned here can be seen in #58169
This pull request is stale because it has been open for thirty days with no activity. Please [update](https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#updating-your-pull-request) and respond to this comment if you're still interested in working on this. @pandas-dev/pandas-core I'd like to start a vote soon but I'd really appreciate more input from the team before doing that. I think one of the main changes in this proposal compared to our current practice, is to more consistently use first a DeprecationWarning and then FutureWarning for higher visibility (this was one of the points that came out of the discussion with a downstream package author in https://github.com/pandas-dev/pandas/issues/54970, and triggered doing this PDEP I think). 
And to be explicit, I am +1 on that proposal.  


> I think one of the main changes in this proposal compared to our current practice, is to more consistently use first a DeprecationWarning and then FutureWarning for higher visibility (this was one of the points that came out of the discussion with a downstream package author in #54970, and triggered doing this PDEP I think). 

Exactly.
 Planning to start the vote in 15 days if there is no unresolved discussion by then. I just voted for this but wanted to add a comment here: As a developer I think it would be helpful to guide users what to do in these situations in docs, hyper linked from the console-message. My users may have any version of pandas installed (often corporates use quite old versions packaged internally) which means a solution must work across multiple versions. My code often contains version "ifs" and then different branches with "TODO"s as remnants to tidy it up once my software has migrated to a minimum versions of pandas.

Sometimes deprecations can be avoided using current code, other times it uses new implementations which need different types of solutions. > As a developer I think it would be helpful to guide users what to do in these situations in docs, hyper linked from the console-message. 

It is usually the case that we guide users how to deal with a deprecation in the warning message if possible, as explicitly mentioned in the PDEP:
> A deprecation's warning message should: - Mention how to achieve similar behavior if an alternative is available.
 Thanks @Aloqeely for working on this.

As a reader of this document, I would ask, "What is the main purpose of PDEP-17?" The abstract states, "This PDEP defines pandas' backwards compatibility and deprecation policy." This seems somewhat unclear as the motivation behind the PDEP since we already have a Version policy. It becomes apparent from following the in-depth discussion that the actual motivation was #54970. This should probably be conveyed in the document for future readers, so they don't need to dig deep into the discussion.

On a related note, to avoid ambiguity, does this document wholly supersede our current policy? The abstract mentions "The main additions ... ," but there is also a removal from the current policy. Specifically, the warning should include the pandas version in which the deprecation will be enforced is being removed. This is my understanding from the discussion, but I cannot see this explicitly mentioned.

Am I correct in thinking that the published policy on the web will be the text in the General policy section only and in its entirety, and not any modifications to the current policy?

Regarding the Public API, a common practice in the past has been to revert changes that break another established package and discuss the issue. Other packages may use experimental features or the internal API, and we do our best to accommodate that, even if sometimes reluctantly.

All that said... +1 @Aloqeely - can you update the PR to "Accepted". > It becomes apparent from following the in-depth discussion that the actual motivation was https://github.com/pandas-dev/pandas/issues/54970. This should probably be conveyed in the document for future readers, so they don't need to dig deep into the discussion.

Agreed

> Am I correct in thinking that the published policy on the web will be the text in the General policy section only and in its entirety, and not any modifications to the current policy?

No, the published policy will be updated to include all the additions and removals discussed here.

> can you update the PR to "Accepted".

Alright Thanks @Aloqeely!