diff --git a/APE2.rst b/APE2.rst index 26da292e..e899b21e 100644 --- a/APE2.rst +++ b/APE2.rst @@ -5,7 +5,7 @@ author: Erik Tollerud date-created: 2013 November 18 -date-last-revised: 2013 December 11 +date-last-revised: 2023 May 31 date-accepted: 2013 December 10 @@ -13,74 +13,79 @@ type: Process status: Accepted +revised-by: Thomas Robitaille, Pey Lian Lim, Simon Conseil - 2023 May 15 - Rewritten following the approval of APE 21 to no longer have Long Term Support (LTS) versions + Abstract -------- -This APE describes the general plan for timing of releases and their version -numbers. The basic premise is a 6-month cycle for new feature releases, with -releases designated "long-term support" (LTS) releases every two years. Bugfix -releases occur as needed, on both the current feature release and the LTS -releases. - +This APE describes the general plan for timing of releases of the core package +and their version numbers. The basic premise follows semantic +versioning: *major* releases (e.g., 6.0.0) every year (or longer), *minor* +releases (e.g., 6.1.0) typically every six months in between, and *bugfix* +releases (e.g., 6.1.2) as needed between minor releases. Detailed description -------------------- -The release plan through version 0.3 has been somewhat haphazard, with releases -when a certain set of features are judged "ready", but without a clear sense of -how long those features will take. This has lead to concerns that new features -are spending a long time in the development version because *other* features are -not yet complete. At the same time, some larger institutions and facilities -have expressed concern that there is not a clearly-stated support cycle for -Astropy versions. That is, it is not clear if a given version will be supported -via critical bug fixes if it is not the latest version. This was voiced as a +The release plan prior to v0.3 was somewhat haphazard, with releases carried out when a +certain set of features were judged "ready", but without a clear sense of how +long those features would take. This led to concerns that new features were +spending a long time in the development version because *other* features were +not yet complete. At the same time, some larger institutions and facilities had +back then expressed concern that there was not a clearly-stated support cycle for +Astropy versions. That is, it was not clear if a given version would be supported +via critical bug fixes if it was not the latest version. This was voiced as a concern because facilities will not always want to upgrade to the latest -version, but do want to be sure major bugs will get addressed. - -Release scheduling and LTS -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These issues were discussed in the 2013 Coordination Meeting, and the following -proposal represents a consensus from that meeting on the solution, with some -modifications based on community feedback after the meeting. Starting with -version 0.4 , Astropy will have a feature release at least as often as every six -months. Releases between feature releases will only contain bugfixes, not new -features. (See the "Releases and backwards compatibility" section below for more -on what is considered a bug fix). - -Additionally, some feature releases will be designated "long-term support" (LTS) -releases, and these will continue to receive bugfixes for at least two years -(i.e., typically 3 regular feature releases will follow an LTS release). This -addresses the first issue by applying a time-based release cycle, meaning no -feature will need to wait more than six months before reaching users. -Simultaneously, it addresses the second concern by providing a guarantee to -facilities that if they use an LTS, they can count on releases fixing critical -bugs for at least two years. Finally, the LTS releases also act as a convenient -time to submit new Astropy journal papers. - -Version numbering -^^^^^^^^^^^^^^^^^ - -To match this release plan, Astropy will adopt a version numbering scheme of the -form ``x.y.z``, where ``z`` is advanced on a bugfix release, ``y`` is advanced -for a feature release that is *not* an LTS release, and ``x`` is advanced on an -LTS (which also resets ``y`` to 0). So starting from the first LTS release, the -version number schedule might be:: - -* 1.0.0 (LTS release) -* 1.0.1 -* 1.0.2 -* 1.1.0 (six months after 1.0.0) -* 1.1.1 -* 1.0.3 -* 1.1.2 -* 1.2.0 (six months after 1.1.0) -* 1.2.1 -* 1.3.0 (six months after 1.2.0) -* 1.0.4 -* 1.3.1 -* 2.0.0 (LTS release, six months after 1.3.0) +version, but do want to be sure major bugs will get addressed. This led to the +initial version of this APE following discussions at the 2013 Coordination +Meeting. This APE is a living document and is meant to reflect the latest +release guidelines (prior versions can be found in `Previous versions of this +APE`_). + +Release versioning and scheduling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The release cycle for the core package should be as follows: + +* Major releases every year (or longer). These are releases that can introduce breaking + API changes, and should be numbered as x.0.0 (e.g., 6.0.0). +* Minor releases by default every six months in between major releases (or more + frequent if needed). These releases should minimize any API changes and focus + on adding new features. +* Bugfix releases as needed between minor releases. + +As an example, starting from the 6.0.0 release, the version number schedule might be: + +* 6.0.0 +* 6.0.1 +* 6.0.2 +* 6.1.0 (six months after 6.0.0) +* 6.1.1 +* 6.1.2 +* 7.0.0 (six months after 6.1.0, one year after 6.0.0) + +In the above scenario, we would adopt the default 6-month release schedule, and +introduce a new major version with breaking changes one year later. However, the +release schedule could also look like the following: + +* 6.0.0 +* 6.0.1 +* 6.0.2 +* 6.1.0 (three months after 6.0.0) +* 6.1.1 +* 6.1.2 +* 6.2.0 (six months after 6.1.0) +* 6.2.1 +* 6.3.0 (four months after 6.2.0) +* 6.3.1 +* 6.3.2 +* 6.3.3 +* 7.0.0 (five months after 6.3.0, 18 months after 6.0.0) + +In the above hypothetical scenario, the developers have decided to release minor +releases more frequently than every six months, and a year after 6.0.0 there was +no need for a major version, so this was delayed until 18 months after 6.0.0. Feature freeze/testing calendar ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -97,48 +102,97 @@ additions are still acceptable. The standard calendar for a release will be: This is not meant to be an exactly strict calendar, as the day of the week, existence of holidays, and degree of readiness of key features or critical bug -fixes necessitate slop in the exact timing. So more what you'd call guidelines -than actual rules. +fixes necessitate slop in the exact timing. Rapid Feature Releases ^^^^^^^^^^^^^^^^^^^^^^ -This plan is not meant to exclude the possibility of releases *more* frequent +This plan is not meant to exclude the possibility of minor releases *more* frequent than every six months. Six months should be considered both the maximum and the default timeline, but a *shorter* time between releases is allowable, if the -community agrees it is worthwhile. When/if this happens, the subsequent LTS -release should be timed such that is at least two years after the last LTS, even -though that may mean there are more than 3 releases between the LTSs. +community agrees it is worthwhile. When/if this happens, the subsequent major +release should be timed such that is at least one year after the last major release, even +though that may mean there are more than one minor release between the major releases. For example, if a new feature is perceived by the Astropy developer community as -being of great importance, and is completed only three months after the v1.0 -release, a v1.1 release could occur at that time. Once that release has -completed, the release clock is "reset", so v1.2 would be released six months -after v1.1, even though it is not yet 12 months after v1.0. The next two -releases would then be v1.3 and v1.4, because v1.4 would only be 21 months after -v1.0. v2.0 would then either come three months or six months later, depending on -how much work is planned to be new in v2.0. +being of great importance, and is completed only three months after the v6.0.0 +release, a v6.1.0 release could occur at that time. Once that release has +completed, the release clock is "reset", so v6.2.0 would be released six months +after v6.1.0, even though it is not yet 12 months after v6.0.0. The next release +could then be v7.0.0 three or more months after v6.2.0, or could also be another +minor release. Releases and backwards compatibility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As defined here, a "bugfix release" must not break backwards compatibility as -defined by the public API, and it also should not introduce new major features. -The exception to this is cases where the API has an actual mistake that needs to -be fixed, such as a function argument that is missing but was clearly intended -to be there. Further, a bugfix release *can* include documentation improvements, -and in the future there may be some sort of "sandbox" package to act as a -preview or testbed for new additions to come in the next feature release. - -Feature releases do *not* guarantee backwards compatibility with previous -releases. However, all backwards incompatible changes should always be -mentioned in the release notes for a new version. Furthermore, when possible, a -backwards incompatible change should generate an `AstropyDeprecationWarning` for -at least one feature release version before actually making the change -permanent, to allow codes to transition to the new interface. A future APE may -add to or change this with a more concrete policy on when and for how long -something should be deprecated. - +The guidelines in relation to API changes and backward compatibility are as follows: + +* API changes (i.e., modifications as opposed to additions) should only be + carried out in major releases. +* Any API changes should be preceded by deprecation warnings that should be + visible to users for at least a year prior to the API change + being carried out. +* API changes should be documented, with clear guidance on what is changing, + why the change is being made, and how to migrate existing code to the new behavior. +* 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. +* The following will not be considered to be part of the API and can therefore + be changed in bugfix and minor releases: + + * Changes to warning messages + * Changes to exception messages + * Changes to the ``__repr__`` or ``__repr_*__`` of objects + + However, exception and warning *types* will be considered to be part of the + API. + +As with all guidelines, there are exceptions where we can deviate from these guidelines: + +* API changes can be carried out in major releases without deprecation if it is + not possible to have a deprecation phase due to the nature of the change. +* Changes breaking or changing the behavior of code may be needed in order to + fix bugs. Such changes can be made in bugfix or minor releases and do not need + to be considered API changes. +* Changes to exception or warning types may occasionally be done in minor + releases. + +These exceptions will require judgment calls on the part of maintainers, but any +such changes should be minimized as much as possible and clearly communicated to +users (see `Communication with users`_). + +Documentation and performance improvements can be made in bugfix releases as long +as they do not involve any changes or additions to the API. + +Communication with users +^^^^^^^^^^^^^^^^^^^^^^^^ + +It is imperative that we communicate effectively with users so that they understand +what to expect from different releases: + +* We should include documentation for the core package that describes the + release policy above, namely that in general minor releases will not + break/remove functionality, but that major releases might, and also explaining + what is considered API. + +* We should ensure that any changes in releases which deviate from the + guidelines above are clearly communicated to users - for example any API/breaking + changes in minor releases should be included in the "What's New" page for the + minor release. + +* Deprecations should always be mentioned in the changelog, as well as any + removal of deprecated code/API changes. We do not specify how exactly this + should be done, but note that, e.g., Numpy release notes have separate sections + entitled *Deprecations*, *Expired Deprecations* and *Compatibility Notes* in + their release notes (see `here + `_ for an example) + which is clearer than having a single *API changes* section. + +* Maintainers should be encouraged to advertise pull requests with API changes + that are likely to affect users and developers of other packages to the + developer mailing list, and ensuring that the pull request has adequate time + (at least two weeks) to be reviewed properly. Branches and pull requests -------------------------- @@ -149,22 +203,8 @@ N/A Implementation -------------- -If this APE is accepted, a few organizational steps will be required: - -* The currently under-development version "v0.4" will be the first following - the release cycle. Because v0.3 was released On the last Monday in Nov 2013, - the feature freeze and beta for v0.4 will be scheduled for the last Monday in - April 2014, With a release at the end of May 2014. The milestone on GitHub - will thus need to be updated to match this. -* The first LTS release (v1.0) will then come six months after v0.4, so an - appropriate milestone will need to be added to GitHub. Following that, - milestones should be added as needed to reflect the versioning scheme - described in this APE. -* The documentation should be updated to mention the existence of LTS releases - and make it clear that they come with a promise of two years of bug fixes (as - needed). It should also add a link to this APE so that those interested in the - numbering scheme can look here for details. - +Whenever this APE is updated, the core package documentation should be updated +to reflect the latest guidelines described above: https://github.com/astropy/astropy/pull/14713 Backward compatibility ---------------------- @@ -175,20 +215,7 @@ N/A Alternatives ------------ -An alternative version numbering scheme mentioned on astropy-dev was to continue -the current scheme of ``0.x.y``, and simply append `-LTS` for LTS releases. The -disadvantage of this approach is that the first version number is then rendered -essentially meaningless. That is, given its nature as a research library, it is -unlikely to ever be "feature-complete", and hence there is no clear break point -for a 1.0 version. The scheme proposed here simply assigns a different meaning -to the major version as "number of LTSs since the start of the project". - -Another alternative is to use `semantic versioning `_. The -disadvantage of that approach for Astropy is that it is very likely that *all* -versions in the foreseeable future will break backwards compatibility to some -extent. In semantic versioning, this would mean all versions would need to be -of the form ``x.0.y``, rendering the minor version number meaningless. - +N/A Decision rationale ------------------ @@ -200,3 +227,8 @@ original proposal was the addition of the idea that *less than* six month releases were acceptable. The above content reflects those suggestions, and the APE was accepted 12/10/13, as there were no significant objections from the community. + +Previous versions of this APE +----------------------------- + +* 2013-12-10 [`DOI `_] [`GitHub `_] diff --git a/APE21.rst b/APE21.rst new file mode 100644 index 00000000..4d883cb5 --- /dev/null +++ b/APE21.rst @@ -0,0 +1,146 @@ +Ending Long Term Support Releases +--------------------------------- + +author: Thomas Robitaille, Pey Lian Lim, Simon Conseil + +date-created: 2023 February 16 + +date-last-revised: 2023 May 15 + +date-accepted: 2023 May 31 + +type: Process + +status: accepted + + +Abstract +-------- + +This APE proposes to no longer designate any releases of the core package as +being "long-term support" (LTS) and provide guidance on how to handle API +changes and deprecations. + + +Detailed description +-------------------- + +Motivation +^^^^^^^^^^ + +The original `APE 2: Astropy Release Cycle and Version Numbering +`_ describes the release cycle for the +core astropy package, which consists of major releases every 6 months that add +new features (e.g., v5.2), and releases in between these that are limited to +fixing bugs or updating documentation (e.g., v5.2.1). Every 2 years, major +releases are designated as being LTS (e.g., v5.0) and we have committed to +having bugfix releases for this version (e.g., v5.0.3) for up to 2 years. + +At the start of the project, having LTS releases was critical for acceptance by +large organizations/projects for which stability is paramount, as the core +package went through significant API changes between versions due to the +youth of the project and LTS releases were a way to shield against such +changes, or at least reduce disruption to be every 2 years. + +LTS releases are however not without cost: + +* While we use infrastructure to automate backporting fixes to release branches, + in practice the LTS branch diverges more and more from the main development + branch and automated backports are more likely to fail as time goes on, + requiring human effort to manually perform the backports, which can sometimes be + non-trivial. +* Even once fixes are backported to the LTS branch, carrying out releases is not + fully automated and requires manual steps, so having to do bugfix releases for + both the latest release branch and LTS branch puts an additional burden on the core + package release team. + +In addition, it is not clear that LTS releases are needed anymore - now that the +core package is over ten years old, it has reached a much higher level of +stability. Most packages in the scientific Python ecosystem do not have LTS +releases, and there is no longer a strong argument for having this in astropy +either. + +Proposed release procedure +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This APE proposes the following: + +* No longer designate any releases as LTS. +* Refer to the x.0.0 releases (e.g., v6.0.0) as *major*, x.x.0 releases (e.g., + v6.1.0) as *minor*, and x.x.x releases (e.g., v6.1.2) as *bugfix* releases + (essentially `semantic versioning `_) +* Use the x.x.0 format for the first major/minor release in a cycle, rather than + the x.x format previously used, as this is more standard practice with + semantic versioning. +* Keep the default 6-month release cycle for non-bugfix releases, noting that in + line with `APE 2`_, minor versions can also be released more frequently if + needed. +* Leave at least one year between major releases. If one year after the last + major release there are no breaking changes to be made (such as pending + deprecations to remove) then there is no need to release a major version. + The one year timescale for major releases is a minimum, not a fixed + interval. +* Minimize as much as possible any changes that break API or change results in + minor releases, but be pragmatic and occasionally allow such changes if they + would not affect many users. +* Add deprecation warnings or future warnings in minor and major releases, and + make sure that these are present in released versions for a year before + carrying out the breaking changes in a major release. Therefore, if a deprecation + warning is added in a major release, the breaking changes can be made in the + following major release. If a deprecation warning is added a few months before + a major release, the breaking changes can only be made in the subsequent major + release. + +With this in place, we would effectively be striving to maximize stability over +one-year periods but users would see deprecation warnings to prepare them for +changes. This is in contrast to the current LTS system where users might not see +a deprecation warning until the next LTS release as deprecations are not typically +backported. + +As astropy becomes increasingly mature and stable, and since as described above +the 1-year timescale between major releases is a minimum, the interval between +major releases may become arbitrarily longer, and the package may reach a stage +when the major version is no longer or very rarely increased. + +Guidelines on deprecations and API changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To avoid duplication, guidelines on deprecations and API changes as well as +recommendations for communication with users will be added directly to `APE 2`_. + +Branches and pull requests +-------------------------- + +Updates to the core package documentation: https://github.com/astropy/astropy/pull/14713 + +Implementation +-------------- + +This APE proposes to continue supporting the v5.0.x LTS series but to not +designate v6.0.0 as LTS. + +Changes to `APE 2`_ can be reviewed in https://github.com/astropy/astropy-APEs/pull/82 + +After acceptance of this APE, the documentation for the core package should be +updated appropriately: https://github.com/astropy/astropy/pull/14713 + +Backward compatibility +---------------------- + +N/A + +Alternatives +------------ + +We could keep the current release workflow - however as mentioned above this has +a maintenance cost and it is not something that is done by most other major +packages in the scientific Python ecosystem. + +Decision rationale +------------------ + +There is broad consensus in the community that the old model of LTE releases is no longer required, given the +stability that the astropy core package has reached. On the other hand, the maintenance burden described in this APE binds significant resources that are needed in other parts of the project. Thus, this APE is accepted +to simplify the workflow. + +.. _APE 2: https://doi.org/10.5281/zenodo.1043887