We should have a way to track deprecations

[pllim]

@saimn

About APE2/21: I think we should have a way to track deprecations, to know when things can be removed. Pandas uses tickets for that (pandas-dev/pandas#50578, and also pandas-dev/pandas#44823 to track upcoming breaking changes). We probably already have some tickets for specific tasks, but centralizing the information seems useful ?

(Those issues are updated by https://github.com/pandas-dev/pandas/blob/main/.github/workflows/deprecation-tracking-bot.yml )

@pllim

I have been opening issues to remove stuff with mention of a minimal milestone that it should be done. But I can't keep track of everything. To have a meta issue like that, we need someone to manage the list and make sure work gets done. Since we use @deprecated decorator with a "since", I wonder if this can be automated... 🤔

@saimn

The other option is to use individual tickets milestoned to the next major version, but having all the info in one ticket seems useful for planning/tracking work to be done. Maybe some grepping with @deprecated can help indeed.

(@WilliamJamieson voiced support for individual tickets. @pllim also thinks this way is more flexible in case some of them are not able to be removed at the planned timeline. @taldcroft and @eerovaher preferred one meta-issue to track them all like Pandas.)

@pllim

Regardless which way we go with, there is some manual work up-front to play catch up before we can even do the automation part.

astropy-dev mailing list: https://groups.google.com/g/astropy-dev/c/SbAnzEEdFxw

[eerovaher]

The good thing about manually grepping for @deprecated is that it works. The bad thing about it is that it is manual. Introducing some automation to this process could be an improvement.

The reason I would prefer a single meta-issue over an individual issue for each piece of deprecated code is that when a release date is approaching, but there is still deprecated code left to remove, then it would be simple to pin the meta-issue to help attract developer attention.

[pllim]

Re: grepping -- It is not foolproof as some are deprecated using warnings.warn or another methods for their own reasons. Also extra work if "since" is on a different line as the decorator, as black likes to force us to do.

[pllim]

Comments from astropy-dev as of 2023-07-10

---

Some years ago I need some kind of deprecation policy. My final approach was some decorators and functions around the deprecate package

https://github.com/quatrope/scikit-criteria/blob/dev/skcriteria/utils/deprecate.py

This an example of the usage of the deprecate

https://github.com/quatrope/scikit-criteria/blob/dev/skcriteria/core/data.py#L533-L558

Feel free to copy or be inspired by the code

@juanbc (I think)

Editorial comment: Kinda looks like our own @deprecate decorator...

---

If it helps, here is the LSST deprecation policy (it's undergoing some revision now about the timeline, but the basic plan will be the same):

https://developer.lsst.io/stack/deprecating-interfaces.html

Essentially: code is marked deprecated on main, deprecation goes into release X, code can be removed after release X+1. That is tracked by making the deprecation ticket block release X (if e.g. it came from an RFC that had not yet been implemented, but everyone wants it before X comes out), and the release X+1 ticket blocks the removal ticket, while release X+2 is blocked by the removal ticket. That ensures that we know what removals to do before a given release.

This does require creating your release tickets multiple releases out, but that can be helpful for keeping track of planned features much further in the future.

@parejkoj

Editorial comment: Kinda looks like our own @deprecate decorator also, plus deprecation policy maybe not unlike our APE 2...