-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from namurphy/versioning
Add PLEP 5 on versioning and releases
- Loading branch information
Showing
1 changed file
with
256 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| PLEP-0005 – PlasmaPy Versioning and Releases | ||
| ============================================ | ||
|
|
||
| +-------------------+----------------------------------+ | ||
| | PLEP | number | | ||
| +===================+==================================+ | ||
| | title | PlasmaPy Versioning and Releases | | ||
| +-------------------+----------------------------------+ | ||
| | author(s) | Nick Murphy and Stuart Mumford | | ||
| +-------------------+----------------------------------+ | ||
| | contact email | namurphy@cfa.harvard.edu | | ||
| +-------------------+----------------------------------+ | ||
| | date created | 2017-10-14 | | ||
| +-------------------+----------------------------------+ | ||
| | date last revised | 2018-09-17 | | ||
| +-------------------+----------------------------------+ | ||
| | type | process | | ||
| +-------------------+----------------------------------+ | ||
| | status | in preparation | | ||
| +-------------------+----------------------------------+ | ||
|
|
||
| Brief Description | ||
| ----------------- | ||
|
|
||
| PlasmaPy final releases will be of the form ``MAJOR.MINOR.PATCH`` | ||
| where ``MAJOR``, ``MINOR``, and ``PATCH`` are non-negative integers | ||
| that are always present. During the development phase (when ``MAJOR`` | ||
| equals zero), the public `application programming interface (API) | ||
| <https://en.wikipedia.org/wiki/Application_programming_interface>`__ | ||
| should be considered unstable between minor releases. The first | ||
| development release will be in early 2018, with subsequent development | ||
| releases occurring every six months. Version ``1.0.0`` will be | ||
| released after the API has stabilized and PlasmaPy is ready for | ||
| production use. Starting with version ``1.0.0``, ``MAJOR`` will be | ||
| incremented when there are changes that remove backwards | ||
| compatibility, ``MINOR`` will be incremented when backwards compatible | ||
| functionality is added, and ``PATCH`` will be incremented for bug | ||
| fixes and other changes that do not affect the API. A major or minor | ||
| release should occur no less frequently than every six months, with | ||
| major or long term support releases happening every other year. | ||
|
|
||
| Versioning Specification | ||
| ------------------------ | ||
|
|
||
| PlasmaPy shall have version numbers that are consistent with the | ||
| `Semantic Versioning Specification ``2.0.0`` | ||
| <appendix-semantic-versioning-specification-semver-200>`__ and `PEP | ||
| 440 <https://www.python.org/dev/peps/pep-0440/>`__. | ||
|
|
||
| Version numbers for PlasmaPy shall be of the following format: | ||
|
|
||
| ``MAJOR.MINOR.PATCH[{a|b|rc}N][.devM]`` | ||
|
|
||
| The ``MAJOR``, ``MINOR``, and ``PATCH`` version numbers must always be | ||
| present. The pre-release tags given in square brackets are optional, | ||
| and are absent for final releases which shall be of the form | ||
| ``MAJOR.MINOR.PATCH``. The pre-release tags are ``a`` for an alpha | ||
| version, ``b`` for a beta version, and ``rc`` for a release candidate | ||
| version. The integer ``N`` shall initially be ``0``. The development | ||
| tag ``.devM`` will be appended to versions undergoing development. The | ||
| integer ``M`` shall be the commit number. | ||
|
|
||
| During the initial development phase, ``MAJOR`` will be ``0`` so final | ||
| releases will have version numbers of the form ``0.MINOR.PATCH``. | ||
| ``MINOR`` shall be incremented whenever the public API changes, and | ||
| ``PATCH`` shall be incremented whenever there are backwards compatible | ||
| bug fixes. The API should be considered unstable during the | ||
| development phase and anything may change at any time. | ||
|
|
||
| When the API has stabilized sufficiently across all subpackages and | ||
| PlasmaPy has developed enough for widespread production use, version | ||
| ``1.0.0`` shall be released. At this point, the following conditions | ||
| will apply: | ||
|
|
||
| 1. ``MAJOR`` must be incremented whenever we make incompatible changes | ||
| to the application program interface (API). | ||
|
|
||
| 2. MINOR must be incremented whenever we add backwards compatible | ||
| functionality. | ||
|
|
||
| 3. PATCH must be incremented whenever we make backwards compatible bug | ||
| fixes. | ||
|
|
||
| Semantic Versioning Specification (SemVer) 2.0.0 | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| This section contains the `Semantic Version Specification 2.0.0 | ||
| <http://semver.org/spec/v2.0.0.html>`__ that was authored by Tom | ||
| Preston-Werner and shared under a `CC BY 3.0 | ||
| <http://creativecommons.org/licenses/by/3.0/>`__ license. PlasmaPy | ||
| versioning will occur according to this standard. | ||
|
|
||
| .. rubric:: Semantic Versioning 2.0.0 | ||
| :name: semantic-versioning-2.0.0 | ||
|
|
||
| The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, | ||
| “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in | ||
| this document are to be interpreted as described in `RFC 2119 | ||
| <http://www.faqs.org/rfcs/rfc2119.html>`__. | ||
|
|
||
| 1. Software using Semantic Versioning MUST declare a public API. | ||
| This API could be declared in the code itself or exist strictly | ||
| in documentation. However it is done, it should be precise and | ||
| comprehensive. | ||
|
|
||
| 2. A normal version number MUST take the form X.Y.Z where X, Y, | ||
| and Z are non-negative integers, and MUST NOT contain leading | ||
| zeroes. X is the major version, Y is the minor version, and Z | ||
| is the patch version. Each element MUST increase | ||
| numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. | ||
|
|
||
| 3. Once a versioned package has been released, the contents of | ||
| that version MUST NOT be modified. Any modifications MUST be | ||
| released as a new version. | ||
|
|
||
| 4. Major version zero (0.y.z) is for initial development. Anything | ||
| may change at any time. The public API should not be considered | ||
| stable. | ||
|
|
||
| 5. Version 1.0.0 defines the public API. The way in which the | ||
| version number is incremented after this release is dependent | ||
| on this public API and how it changes. | ||
|
|
||
| 6. Patch version Z (x.y.Z \| x > 0) MUST be incremented if only | ||
| backwards compatible bug fixes are introduced. A bug fix is | ||
| defined as an internal change that fixes incorrect behavior. | ||
|
|
||
| 7. Minor version Y (x.Y.z \| x > 0) MUST be incremented if new, | ||
| backwards compatible functionality is introduced to the public | ||
| API. It MUST be incremented if any public API functionality is | ||
| marked as deprecated. It MAY be incremented if substantial new | ||
| functionality or improvements are introduced within the private | ||
| code. It MAY include patch level changes. Patch version MUST be | ||
| reset to 0 when minor version is incremented. | ||
|
|
||
| 8. Major version X (X.y.z \| X > 0) MUST be incremented if any | ||
| backwards incompatible changes are introduced to the public | ||
| API. It MAY include minor and patch level changes. Patch and | ||
| minor version MUST be reset to 0 when major version is | ||
| incremented. | ||
|
|
||
| 9. A pre-release version MAY be denoted by appending a hyphen and | ||
| a series of dot separated identifiers immediately following the | ||
| patch version. Identifiers MUST comprise only ASCII | ||
| alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be | ||
| empty. Numeric identifiers MUST NOT include leading | ||
| zeroes. Pre-release versions have a lower precedence than the | ||
| associated normal version. A pre-release version indicates that | ||
| the version is unstable and might not satisfy the intended | ||
| compatibility requirements as denoted by its associated normal | ||
| version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, | ||
| 1.0.0-x.7.z.92. | ||
|
|
||
| 10. Build metadata MAY be denoted by appending a plus sign and a | ||
| series of dot separated identifiers immediately following the | ||
| patch or pre-release version. Identifiers MUST comprise only | ||
| ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST | ||
| NOT be empty. Build metadata SHOULD be ignored when determining | ||
| version precedence. Thus two versions that differ only in the | ||
| build metadata, have the same precedence. Examples: | ||
| 1.0.0-alpha+001, 1.0.0+20130313144700, | ||
| 1.0.0-beta+exp.sha.5114f85. | ||
|
|
||
| 11. Precedence refers to how versions are compared to each other | ||
| when ordered. Precedence MUST be calculated by separating the | ||
| version into major, minor, patch and pre-release identifiers in | ||
| that order (Build metadata does not figure into precedence). | ||
| Precedence is determined by the first difference when comparing | ||
| each of these identifiers from left to right as follows: Major, | ||
| minor, and patch versions are always compared numerically. | ||
| Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and | ||
| patch are equal, a pre-release version has lower precedence | ||
| than a normal version. Example: 1.0.0-alpha < 1.0.0. Precedence | ||
| for two pre-release versions with the same major, minor, and | ||
| patch version MUST be determined by comparing each dot | ||
| separated identifier from left to right until a difference is | ||
| found as follows: identifiers consisting of only digits are | ||
| compared numerically and identifiers with letters or hyphens | ||
| are compared lexically in ASCII sort order. Numeric identifiers | ||
| always have lower precedence than non-numeric identifiers. A | ||
| larger set of pre-release fields has a higher precedence than a | ||
| smaller set, if all of the preceding identifiers are | ||
| equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta | ||
| < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < | ||
| 1.0.0. | ||
|
|
||
| Release Schedule | ||
| ---------------- | ||
|
|
||
| Version ``0.1.0`` of PlasmaPy was released in 2018 as a prototype and | ||
| developer’s preview. Subsequent development releases should occur no | ||
| less frequently than every six months, and should occur more | ||
| frequently when important new features are added. Minor releases | ||
| during the development phase shall be supported with patch releases | ||
| until the next minor release. | ||
|
|
||
| Version ``1.0.0`` will be released once PlasmaPy has a stable API that | ||
| users have begun to depend upon. Releases should occur no less | ||
| frequently than every six months. A major release should generally | ||
| happen every two years. According to this schedule there should be about | ||
| three minor releases between each major release. | ||
|
|
||
| Long term support (LTS) releases shall occur roughly once every two | ||
| years. LTS releases shall be supported with maintenance and bug fix | ||
| patches for at least two years or until the next LTS release, whichever | ||
| takes longer. Version ``1.0.0`` should be PlasmaPy’s first LTS release. | ||
| Subsequent LTS releases should generally be the last minor release for | ||
| each major version number. The Coordinating Committee may alter the LTS | ||
| release schedule when appropriate (e.g., when major releases occur more | ||
| or less frequently than every two years). | ||
|
|
||
| Issues, Pull Requests, and Branches | ||
| ----------------------------------- | ||
|
|
||
| - https://github.com/PlasmaPy/PlasmaPy-PLEPs/pull/8 | ||
|
|
||
| - `Semantic Versioning: Why You Should Be Using It | ||
| <https://www.sitepoint.com/semantic-versioning-why-you-should-using/>`__ | ||
|
|
||
| - A `critique of semantic versioning that proposes “romantic | ||
| versioning” <https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e>`__ | ||
|
|
||
| - The SunPy community had a `detailed conversation about switching to | ||
| semantic versioning <https://github.com/sunpy/sunpy-SEP/pull/30>`__. | ||
|
|
||
| Alternatives | ||
| ------------ | ||
|
|
||
| There are `numerous versioning | ||
| schemes <https://en.wikipedia.org/wiki/Software_versioning#Schemes>`__ | ||
| that are used by different software projects. These schemes are | ||
| generally less standardized between different projects than semantic | ||
| versioning. Some options include: | ||
|
|
||
| - Version numbers may be of the form ``YY.MM.PATCH`` where ``YY`` | ||
| corresponds to the last two digits of the year and ``MM`` corresponds | ||
| to the digits associated with the month of the release. Ubuntu uses | ||
| this versioning scheme. The advantage of this scheme is that it makes | ||
| it easier to know when a version is out-of-date. A significant | ||
| disadvantage is that this scheme provides no information on backwards | ||
| compatibility. | ||
|
|
||
| - Some software packages have two versioning schemes. Public version | ||
| numbers are easily human readable (e.g., by containing the year) | ||
| whereas developers use a versioning scheme that provides more | ||
| information about the state of development. This alternative is less | ||
| useful for scientific packages where there is less distinction | ||
| between users and developers. | ||
|
|
||
| Decision Rationale | ||
| ------------------ | ||
|
|
||
| Semantic versioning is a well-defined versioning scheme that provides | ||
| users with useful information about whether or not there were any | ||
| backward incompatible changes. This scheme is well-suited to a core | ||
| scientific software package that will require stability. |