APE 2: Clarify next major release meaning in deprecation policy #109
Conversation
in deprecation policy. Co-authored-by: Brigitta Sipőcz <bsipocz@gmail.com>
APE2.rst
Outdated
| @@ -137,7 +137,8 @@ The guidelines in relation to API changes and backward compatibility are as foll | |||
| * New deprecations should not be introduced in bugfix releases. | |||
| * If developers wish to make an API change at a point in time where the next | |||
| release is a major release, they should introduce the deprecation in the major | |||
| release and carry out the change in the following major release. | |||
| release and carry out the change in the following major release | |||
| (i.e., the second feature release after deprecation). | |||
There was a problem hiding this comment.
The added remark clearly contradicts the second example in Release versioning and scheduling
There was a problem hiding this comment.
Agreed; I think using "feature release" here alongside "minor release" may just add to the confusion, unless one wants to make the point that a major release is also a feature release (besides being an API-changing release and a bugfix release). The key points to me really are, as stated above, "the change itself must only be made in a major release" and "the deprecation warning shall be visible for at least a year before that".
But since the release cycle clearly allows for more than two minor/feature releases within a year, giving any number here misses the point imo.
Might be clearer to rephrase that entire bullet to "introduce the deprecation in the next feature release (meaning, regardless whether that happens to be a minor or major release) and carry out the deprecation in the following major release".
With the two conditions above, that might mean both that the time can be longer than one year, and that there is no other major release during the deprecation period (e.g. in that second example, deprecation added in 6.1.0, removal executed in 7.0.0 – 15 months later).
There was a problem hiding this comment.
It is "following major release" that confuses me.
If deprecation is added in 6.1.0, and then the deprecated code removed in 7.0, that is only about 6 months, according to https://github.com/astropy/astropy/wiki/Release-Calendar .
There was a problem hiding this comment.
Right, that only holds in the original wording (the case that the deprecation is also introduced in a major release): since major releases are at least twelve months apart, that would set a minimum time of one year.
In the rephrasing I suggested above, that would have to be "the major release following at least a year after the deprecation".
Since I didn't really change the original meaning, maybe we can get away by not considering this a revision? |
Because I was very confused for a few hours. Thanks to @bsipocz for the clarification!
cc @astrofrog and @saimn as co-authors of the last revision.