Skip to content

Commit

Permalink
Merge pull request #82 from astrofrog/ape-lts
Browse files Browse the repository at this point in the history 
APE 21: APE on ending long term support releases + Updates to APE 2 to reflect new release cycle without LTS
  • Loading branch information
@hamogu
hamogu authored May 31, 2023
2 parents 4d5783c + 6bc2c5b commit 568e92a
Show file tree
Hide file tree
Showing 2 changed files with 298 additions and 120 deletions.
272 changes: 152 additions & 120 deletions APE2.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,82 +5,87 @@ 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

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -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
<https://numpy.org/doc/stable/release/1.24.0-notes.html>`_ 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
--------------------------
Expand All @@ -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
----------------------
Expand All @@ -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 <http://semver.org/>`_. 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
------------------
Expand All @@ -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 <https://doi.org/10.5281/zenodo.1043887>`_] [`GitHub <https://github.com/astropy/astropy-APEs/blob/48f949c05efa4f07ed8915eccdb0cd139c57b6f6/APE2.rst>`_]
Loading

0 comments on commit 568e92a

Please sign in to comment.