Added the definition of Deprecation and made Deprecation Process clearer #21626
Conversation
|
Thanks for the PR. This is going a bit in the right direction. However, as described in #21393 (comment) I think the section needs to be rewritten more fundamentally. |
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
|
@timhoffm No worries, I am learning a lot from you along the process, so no problem. All suggestions were right and good. |
| - The deprecated API should, to the maximum extent possible, remain fully | ||
| functional during the deprecation period. In cases where this is not | ||
| possible, the deprecation must never make a given piece of code do something | ||
| different than it was before; at least an exception should be raised. |
There was a problem hiding this comment.
I think this point ("must never make a given piece of code...") is important and must be kept (possibly reworded).
There was a problem hiding this comment.
@jklymak @timhoffm Do you feel the same way regarding this statement? I think @timhoffm consciously changed that part to make it clear that the old API must (not should) remain functional. Therefore, any ",but..." clause is irrelevant. BTW, this is not my definite opinion, I am just paraphrasing what I think @timhoffm said and I can follow this logic. If it MUST stay functional than we don't need to worry about the "what if it does'nt remain functional" case
There was a problem hiding this comment.
I'm fine with the more stringent statement to keep things simple and as a guide to contributors.
Very occasionally, this list of rules ends up being bypassed. Since this basically has to be done by the lead devs, listing the caveats and how to mitigate them seems unnecessary in a document like this. However, if I were writing the first sentence of the second paragraph I would say
API changes in Matplotlib have to be performed following the deprecation process below, except in very rare circumstances as deemed necessary by the development team.
That makes it clear we can't always live up to the ideals of this process...
There was a problem hiding this comment.
I'm OK with @jklymak's take on this.
There was a problem hiding this comment.
Alright, sounds like a good compromise
doc/devel/contributing.rst
Outdated
| deprecation process. This ensures that users are notified before the change | ||
| will take effect and thus prevents unexpected breaking of code. | ||
|
|
||
| Deprecation process |
There was a problem hiding this comment.
Don't introduce only one subsection of a section. If you want subsections, suggest "Rules" "Introducing..." and "Expiring..." I think it is obvious that these are the "deprecation process"
There was a problem hiding this comment.
Alright, changed the subsection titles and got rid of the obvious (too generic) title "Deprecation process"
Introduced more specific subsection titles since it is obvious that all refer to Deprecations
Adding sentence saying that rare cases might need lead dev attention
… made Deprecation Process clearer
…626-on-v3.5.x Backport PR #21626 on branch v3.5.x (Added the definition of Deprecation and made Deprecation Process clearer)
#21393 @story645 @anntzer @QuLogic @jklymak
I suggest the following changes to make things a bit clearer.