Add a page listing the active deprecations

[maximlt]

Experimenting with adding this page, as I've been working on HEP 2 and think that it'd help maintainers (users too in fact!) if such a page existed and was maintained over time.

For example, I bumped a couple of warnings in #921 and updated the page accordingly.

[hoxbro]

Did you try putting this information in a table?

I don't think we should mention old deprecations. This should ideally be handled by versioning the documentation. As we don't have that, I think it is ok for now.

users too in fact!

TBH, I don't think users will look at a webpage to see deprecations, but I understand your point.

[maximlt]

Did you try putting this information in a table?

Done in 07597fa

I don't think we should mention old deprecations. This should ideally be handled by versioning the documentation. As we don't have that, I think it is ok for now.

I should have explained why I included the deprecation history. It's almost the most important piece of information I need as a maintainer as I want an easy way to know for how long a feature has been deprecated. I had to do so much Github digging when releasing Param 2.0 through the release notes and Github issues/PRs.
In my mind, when a feature is eventually removed from the code base, it is to be removed from this page.

TBH, I don't think users will look at a webpage to see deprecations, but I understand your point.

Just sharing these links I just found (the page I added in this PR is nowhere near these!):

• https://docs.sympy.org/latest/explanation/active-deprecations.html
• https://docs.pytest.org/en/7.1.x/deprecations.html

[hoxbro]

I think there is two conflicting perspective with your last comment, one is what is good for the developer, the second is what is good for the user. I don't see them as the same thing.

I should have explained why I included the deprecation history. It's almost the most important piece of information I need as a maintainer as I want an easy way to know for how long a feature has been deprecated. I had to do so much Github digging when releasing Param 2.0 through the release notes and Github issues/PRs.

This is looking from it as a developer. From a users perspective he doesn't care for previous versions deprecations, he care about his version.

Just sharing these links I just found (the page I added in this PR is nowhere near these!):

May I ask you when did you last look at this? Because I haven't looked at them before, and I would say I use pytest a lot. 🙃

[maximlt]

My main motivation for this PR was to experiment with how to help maintainers better handle deprecations over time, to serve the development of HEP 2. I picked Param because I know more about it's deprecation warnings than any other library, and because it has many active ones so it's a good use case.

I thought that having that as a listing in the docs could also be useful for users. The review shows that this view isn't shared. I think this discussion should take place in HEP 2 with a larger group, so I'm going to close this PR, I can still point to it from HEP 2 as a possible way to improve things.

[philippjfr]

Personally I call out deprecations explicitly in the release notes but do potentially see value in an overview and/or migration guide.