Repository navigation
[Doc]: describe deprecation process more explicitly #21393
Description
Documentation Link
Problem
I'm deeply confused about whether since is the last release that has the arg or the first release without it. It's documented as The release at which this API became deprecated. which I assume is following some convention, but is not clear to me since I do not know the convention.
Suggested improvement
Add a sentence to the since docstring (and possibly to https://matplotlib.org/devdocs/devel/contributing.html#api-changes) saying something like: the last release containing this code. I think https://docs.moodle.org/dev/Deprecation do a good job at illustrating the convention.
Edit: as @QuLogic suggested, don't modify the docstring but explain the deprecation to removal process more explicitly in the API changes part of the dev guide.
Matplotlib Version
dev
Matplotlib documentation version
dev
Activity
QuLogic commentedon Oct 20, 2021
Neither. It is, as documented, when it became deprecated. The release where it's removed is determined by the
removalargument (and by whether anyone remembers to remove it), which defaults to "two minor releases later". There are no decorators for removed API, because, well, they've been removed.story645 commentedon Oct 20, 2021
Ok, so then does the
sincearg mark when the decision was made to deprecate the arg?jklymak commentedon Oct 20, 2021
Its the release where the argument was first deprecated. So if you have a PR with a 3.6 milestone, and you deprecate something you would put since='3.6'
story645 commentedon Oct 20, 2021
@QuLogic made the same point, but the mpl docs on deprecation don't unpack what the 'deprecation' process is. What I'm gathering from your and Elliot's comments is that the since kwarg marks when the deprecation process was initiated for whichever arg is being deprecated.
jklymak commentedon Oct 20, 2021
The process is that you get your instance of
warn_deprecatedinto the codebase!QuLogic commentedon Oct 20, 2021
If you're asking for more documentation on the deprecation process from deprecation to removal, then yea, I think that could be written. I'm not sure it belongs in
warn_deprecated, but a reference to the API change page you had is a good idea.[-][Doc]: deprecation decorator 'since' arg[/-][+][Doc]: describe deprecation process more explicitly[/+]story645 commentedon Oct 20, 2021
Totally agree, I think better documenting the process in the dev guide & cross linking those docs in warn_deprecate will probably solve this issue as far as I'm concerned.
(Updated name & description to include this suggestion).
anntzer commentedon Oct 20, 2021
Is https://matplotlib.org/devdocs/devel/contributing.html#api-changes not sufficient?
story645 commentedon Oct 20, 2021
It's written a little too much assuming that the audience knows what deprecation means in the exact context it's written in, so it took a few rereads for me to get that
since(I think?) refers toI think small changes should do the trick: a sentence defining deprecation, reworking the sentence above so it's clearer that's what the since keyword is referring to, maybe rearrange bullets so that the bullet points that are tied to the warn_deprecate params are clustered together.
Edit: but as a first pass, cross-linking to those docs would definitely be an improvement.
timhoffm commentedon Nov 13, 2021
A deprecation is not an API change; it's a note on an upcoming API change. Deprecating an API is mandatory before changing it.
I think this whole API section is flawed and would need to be rewritten from scatch:
Messages:
I think this bullet point from the existing docs is wrong:
The old API must remain fully functional during the deprecation period.
Ok, I agree that clarity is good. OTOH I'm not too worried here on loosing audience. Generally, If you don't know what a deprecation is, you most likely won't have the experience to estimate the consequences of an API change and should leave this to more experienced people.
timhoffm commentedon Nov 13, 2021
Yes, I meant "consistency".