| SEP | 9 |
|---|---|
| title | Release Pattern for SunPy Core |
| author(s) | Stuart Mumford Russell Hewett |
| contact email | [email protected] |
| date-creation | 2018-12-13 |
| type | process |
| discussion | #40 |
| status | accepted |
This SEP defines a release pattern for the SunPy core package and defines a versioning system. Since SunPy is being used more widely both by users as well as developers as a dependency, it is important to have clear and predictable releases. This is especially important to support other Python packages which have SunPy as a dependency (e.g. affiliated packages). A predictable release and support cycle for the SunPy core package will aid these packages in planning their own development cycle.
The focus of this SEP is not to prescribe how quickly the core package improves through the introduction of new features or API changes but how and when release occur and how they are described.
This SEP prescribes that there will be two planned releases of the SunPy core package per year with at least 4 months (preferably 6 months) between these releases. It is suggested that these occur in the months of May and November based on the current release schedule of the astropy core package. It is the responsibility of the lead developer to plan a release schedule that is consistent with these requirement and to present it to the Board at the beginning of every year, if it differs from this recommendation. Releases are recommended to be timed to pertinent release cycles of upstream packages. The lead developer can at their discretion do an out of cycle release if they feel there is sufficient justification.
This SEP defines two categories of SunPy release, a Long Term Support (LTS) release and a short-support or non-LTS release. Both types of releases will be supported by bug fixes and documentation upgrades but for differing amounts of time. The first release of the year shall be a LTS release, which shall be supported for 12 months or until the next LTS release. The second release of the year will not be an LTS release and will be supported for 6 months or until the next release. Support periods can be extended beyond the requirements here if needed.
The objective of this support cycle is to balance the desire to provide a release cycle for people who wish to experience minimal changes to SunPy while minimizing the maintenance burden on the SunPy developers. This release schedule is consistent with the resources available at the time of writing. Should more (or less) resources become available this topic must be re-evaluated.
The following versioning system shall be used.
X.Y.z
Where the three components have the following meanings:
- X. is the LTS version number, this will be incremented with every LTS.
- Y. is the release counter, this will be 0 for LTS releases and increment for each intermediate release.
- z. is the bug fix number, and is to be incremented for any bug fix releases.
An example release sequence, following this scheme, would look like this:
- 1.0.0 is an LTS release, released November 2019.
- 1.0.1 is a bugfix to the LTS release, released December 2019.
- 1.1.0 is a short support release, released May 2020.
- 1.0.2 and 1.1.1 are bugfix releases, released June 2020, to fix a current bug and backport the fix to the LTS version.
- 1.2.0 is an unplanned short support release, released August 2020
- 2.0.0 is an LTS release, released November 2020.
Every numbered release shall be associated with a Digital Object Identifier (DOI) and it is recommended that major LTS releases be supported by a journal article if appropriate.
The SunPy core package must always document API changes, in the CHANGELOG and in the user documentation. Where practical a side-by-side comparison of old and new functionality will be provided.
In addition to this, where possible, code will emit deprecation warnings to inform users of planned changes to or removal of API. Warnings will only be emitted when an alternative option exists for the functionality, or the functionality is to be completely removed.
All effort will be made to provide at least one LTS release where functionality which is to be changed or removed emits deprecation warnings. This is to ensure that users who move from LTS release to LTS release still receive a deprecation warning about changes to the API.
Accepted by a vote of the board on 26-Jun-2019.