From db6526b2eb707c9fc611e43cdbf2d1da47a2ef19 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Sun, 15 Oct 2017 14:14:53 -0400 Subject: [PATCH 1/7] Add first draft of PLEP on versioning and releases --- PLEP-0005.md | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 PLEP-0005.md diff --git a/PLEP-0005.md b/PLEP-0005.md new file mode 100644 index 0000000..6941d27 --- /dev/null +++ b/PLEP-0005.md @@ -0,0 +1,195 @@ +# PLEP-0005 -- PlasmaPy Versioning and Releases + +| PLEP | number | +|-------------------|---------------------------------------| +| title | PlasmaPy Versioning and Releases | +| author(s) | Nick Murphy | +| contact email | namurphy@cfa.harvard.edu | +| date created | 2017-10-14 | +| date last revised | 2017-10-14 | +| type | process | +| status | in preparation | + +# Abstract + +This PLEP describes the versioning scheme for PlasmaPy core and +affiliated packages, and the anticipated release cycle for the core +package. + +# Versioning Specification + +PlasmaPy shall have version numbers that are consistent with the +Semantic Versioning Specification (SemVer) `2.0.0` 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. 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 the version that is being +developed. The integer `M` shall be the commit number. + +Final releases of PlasmaPy shall be of the form `MAJOR.MINOR.PATCH`. + +1. `MAJOR` must be incremented whenever we make incompatible changes to + the application program interface (API), starting with version + `1.0.0`. + +2. MINOR must be incremented whenever we add backwards-compatible + functionality. + +3. PATCH must be incremented whenever we make backwards-compatible bug + fixes. + +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 and anything may +change at any time during the development phase. + +# Release Schedule + +Version `0.1.0` of PlasmaPy will be released in early 2018. This +version will not be intended for production use and should instead be +considered a developer's preview. Bug fixes for version `0.1.0` are +not required and may be incorporated into version `0.2.0` instead of +`0.1.1`. + +Subsequent development releases should occur no less frequently than +every six months, but may occur more frequently if important new +features are added. Starting with version `0.2.0`, minor releases +during the development phase shall be supported with patch releases +until the next minor release. + +Version `1.0.0` shall be released once the PlasmaPy core package has a +stable API that users have begun to depend upon. This release should +occur by 2022. 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 roughly three minor +releases between every 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. The Coordinating Committee may optionally +designate a development release for medium or long term support if +there is significant demand and support for it among PlasmaPy users +and developers. Version `1.0.0` shall be an LTS release. Releases +that occur when the major version number is incremented will generally +be LTS releases. 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 + + + +# 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 than semantic versioning. + +# Decision Rationale + +*This PLEP is in preparation and has not been decided upon.* + +# Appendix: Semantic Versioning Specification (SemVer) 2.0.0 + +*This section contains the Semantic Version Specification +(SemVer) that was authored by Tom Preston-Werner and shared under a +[CC BY 3.0](http://creativecommons.org/licenses/by/3.0/) license.* + +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. + From 81010861c4148a2c2704b30d890cfe4f254527c4 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Tue, 17 Oct 2017 23:42:54 -0400 Subject: [PATCH 2/7] Revise release schedule --- PLEP-0005.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/PLEP-0005.md b/PLEP-0005.md index 6941d27..3219b51 100644 --- a/PLEP-0005.md +++ b/PLEP-0005.md @@ -55,24 +55,18 @@ change at any time during the development phase. # Release Schedule -Version `0.1.0` of PlasmaPy will be released in early 2018. This -version will not be intended for production use and should instead be -considered a developer's preview. Bug fixes for version `0.1.0` are -not required and may be incorporated into version `0.2.0` instead of -`0.1.1`. - -Subsequent development releases should occur no less frequently than -every six months, but may occur more frequently if important new -features are added. Starting with version `0.2.0`, minor releases +Version `0.1.0` of PlasmaPy will be released in early 2018 as a +prototype and developer's preview. Subsequent development releases +should occur no less frequently than every six months, but may occur +more frequently if 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` shall be released once the PlasmaPy core package has a -stable API that users have begun to depend upon. This release should -occur by 2022. 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 roughly three minor -releases between every major release. +Version `1.0.0` will be released once the PlasmaPy core package 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 From ca4436cf899ff67736ba179948161003dd61ca31 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Thu, 9 Nov 2017 21:11:10 -0500 Subject: [PATCH 3/7] Revise PLEP on versioning and releases --- PLEP-0005.md | 313 +++++++++++++++++++++++++++++---------------------- 1 file changed, 181 insertions(+), 132 deletions(-) diff --git a/PLEP-0005.md b/PLEP-0005.md index 3219b51..444161b 100644 --- a/PLEP-0005.md +++ b/PLEP-0005.md @@ -6,21 +6,35 @@ | author(s) | Nick Murphy | | contact email | namurphy@cfa.harvard.edu | | date created | 2017-10-14 | -| date last revised | 2017-10-14 | +| date last revised | 2017-11-09 | | type | process | | status | in preparation | -# Abstract - -This PLEP describes the versioning scheme for PlasmaPy core and -affiliated packages, and the anticipated release cycle for the core -package. - -# Versioning Specification +## 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 occur 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 minor or major release should occur every six +months, with major or long term support (LTS) releases occuring every +other year. + +## Versioning Specification PlasmaPy shall have version numbers that are consistent with the -Semantic Versioning Specification (SemVer) `2.0.0` and [PEP -440](https://www.python.org/dev/peps/pep-0440/). +[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: @@ -28,36 +42,139 @@ Version numbers for PlasmaPy shall be of the following format: 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. 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 the version that is being -developed. The integer `M` shall be the commit number. +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. -Final releases of PlasmaPy shall be of the form `MAJOR.MINOR.PATCH`. +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. The principal ideas behind semantic +version are that: -1. `MAJOR` must be incremented whenever we make incompatible changes to - the application program interface (API), starting with version - `1.0.0`. +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 +2. MINOR must be incremented whenever we add backwards compatible functionality. -3. PATCH must be incremented whenever we make backwards-compatible bug +3. PATCH must be incremented whenever we make backwards compatible bug fixes. -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 and anything may -change at any time during the development phase. - -# Release Schedule +### 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. + +> #### 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 will be released in early 2018 as a prototype and developer's preview. Subsequent development releases -should occur no less frequently than every six months, but may occur +should occur no less frequently than every six months, and may occur more frequently if important new features are added. Minor releases during the development phase shall be supported with patch releases until the next minor release. @@ -74,116 +191,48 @@ patches for at least two years or until the next LTS release, whichever takes longer. The Coordinating Committee may optionally designate a development release for medium or long term support if there is significant demand and support for it among PlasmaPy users -and developers. Version `1.0.0` shall be an LTS release. Releases -that occur when the major version number is incremented will generally -be LTS releases. The Coordinating Committee may alter the LTS release +and developers. Version `1.0.0` should be an 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 +## 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/) -# Alternatives +- A [critique of semantic versioning that proposes "romantic + versioning"](https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e) -- 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 than semantic versioning. +- The SunPy community had a [detailed conversation about switching to + semantic versioning](https://github.com/sunpy/sunpy-SEP/pull/30). -# Decision Rationale +## Alternatives -*This PLEP is in preparation and has not been decided upon.* +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: -# Appendix: Semantic Versioning Specification (SemVer) 2.0.0 - -*This section contains the Semantic Version Specification -(SemVer) that was authored by Tom Preston-Werner and shared under a -[CC BY 3.0](http://creativecommons.org/licenses/by/3.0/) license.* - -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. +- 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 + +*This PLEP is in preparation and has not been decided upon.* From e9c61dd992f7493ecffa74550f51adceb2b85c14 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Mon, 13 Nov 2017 17:36:58 -0500 Subject: [PATCH 4/7] Update and add co-author to PLEP on versioning --- PLEP-0005.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PLEP-0005.md b/PLEP-0005.md index 444161b..ee9a9a4 100644 --- a/PLEP-0005.md +++ b/PLEP-0005.md @@ -3,10 +3,10 @@ | PLEP | number | |-------------------|---------------------------------------| | title | PlasmaPy Versioning and Releases | -| author(s) | Nick Murphy | +| author(s) | Nick Murphy and Stuart Mumford | | contact email | namurphy@cfa.harvard.edu | | date created | 2017-10-14 | -| date last revised | 2017-11-09 | +| date last revised | 2017-11-13 | | type | process | | status | in preparation | @@ -58,8 +58,8 @@ 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. The principal ideas behind semantic -version are that: +`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). From 8498a4f0a8072000762a7c9acd5f3dab07661e3a Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Fri, 18 May 2018 16:02:03 -0400 Subject: [PATCH 5/7] Revise and update versioning PLEP --- PLEP-0005.md | 55 +++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/PLEP-0005.md b/PLEP-0005.md index ee9a9a4..616a8c1 100644 --- a/PLEP-0005.md +++ b/PLEP-0005.md @@ -6,7 +6,7 @@ | author(s) | Nick Murphy and Stuart Mumford | | contact email | namurphy@cfa.harvard.edu | | date created | 2017-10-14 | -| date last revised | 2017-11-13 | +| date last revised | 2018-05-18 | | type | process | | status | in preparation | @@ -19,20 +19,20 @@ 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 occur after -the API has stabilized and PlasmaPy is ready for production use. +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 minor or major release should occur every six -months, with major or long term support (LTS) releases occuring every -other year. +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 +[Semantic Versioning Specification `2.0.0`](appendix-semantic-versioning-specification-semver-200) and [PEP 440](https://www.python.org/dev/peps/pep-0440/). @@ -72,7 +72,7 @@ will apply: ### Semantic Versioning Specification (SemVer) 2.0.0 -This section contains the [Semantic Version Specification +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 @@ -84,12 +84,12 @@ versioning will occur according to this standard. > “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 @@ -172,30 +172,27 @@ versioning will occur according to this standard. ## Release Schedule -Version `0.1.0` of PlasmaPy will be released in early 2018 as a -prototype and developer's preview. Subsequent development releases -should occur no less frequently than every six months, and may occur -more frequently if important new features are added. Minor releases -during the development phase shall be supported with patch releases -until the next minor release. +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 the PlasmaPy core package 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. +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. The Coordinating Committee may optionally -designate a development release for medium or long term support if -there is significant demand and support for it among PlasmaPy users -and developers. Version `1.0.0` should be an 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). +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 From f25ff32a522aff147a51deb16c9b96a476723182 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Tue, 22 May 2018 15:24:21 -0400 Subject: [PATCH 6/7] Convert PLEP-0005.md to PLEP-0005.rst --- PLEP-0005.md | 235 ----------------------------------------------- PLEP-0005.rst | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 250 insertions(+), 235 deletions(-) delete mode 100644 PLEP-0005.md create mode 100644 PLEP-0005.rst diff --git a/PLEP-0005.md b/PLEP-0005.md deleted file mode 100644 index 616a8c1..0000000 --- a/PLEP-0005.md +++ /dev/null @@ -1,235 +0,0 @@ -# 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-05-18 | -| 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. - -> #### 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 - -*This PLEP is in preparation and has not been decided upon.* diff --git a/PLEP-0005.rst b/PLEP-0005.rst new file mode 100644 index 0000000..1973511 --- /dev/null +++ b/PLEP-0005.rst @@ -0,0 +1,250 @@ +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-05-18 | ++-------------------+----------------------------------+ +| 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) `__ +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`` `__ and +`PEP 440 `__. + +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 `__ that was authored by Tom +Preston-Werner and shared under a `CC 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 `__. + + 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 `__ + +- A `critique of semantic versioning that proposes “romantic + versioning” `__ + +- The SunPy community had a `detailed conversation about switching to + semantic versioning `__. + +Alternatives +------------ + +There are `numerous 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 +------------------ + +*This PLEP is in preparation and has not been decided upon.* From 723ac527a959db6dd869ef7284015e19b3858861 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Mon, 17 Sep 2018 17:55:49 -0400 Subject: [PATCH 7/7] Update PLEP 5 on versioning I added a draft decision rationale too. --- PLEP-0005.rst | 168 ++++++++++++++++++++++++++------------------------ 1 file changed, 87 insertions(+), 81 deletions(-) diff --git a/PLEP-0005.rst b/PLEP-0005.rst index 1973511..6a7e4e8 100644 --- a/PLEP-0005.rst +++ b/PLEP-0005.rst @@ -12,7 +12,7 @@ PLEP-0005 – PlasmaPy Versioning and Releases +-------------------+----------------------------------+ | date created | 2017-10-14 | +-------------------+----------------------------------+ -| date last revised | 2018-05-18 | +| date last revised | 2018-09-17 | +-------------------+----------------------------------+ | type | process | +-------------------+----------------------------------+ @@ -22,50 +22,50 @@ PLEP-0005 – PlasmaPy Versioning and Releases 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) `__ +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) +`__ 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. +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`` `__ and -`PEP 440 `__. +`Semantic Versioning Specification ``2.0.0`` +`__ and `PEP +440 `__. 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 +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 +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. +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 @@ -84,42 +84,42 @@ will apply: Semantic Versioning Specification (SemVer) 2.0.0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section contains the `Semantic Version Specification -2.0.0 `__ that was authored by Tom -Preston-Werner and shared under a `CC BY -3.0 `__ license. PlasmaPy +This section contains the `Semantic Version Specification 2.0.0 +`__ that was authored by Tom +Preston-Werner and shared under a `CC 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 `__. + “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in + this document are to be interpreted as described in `RFC 2119 + `__. 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. + 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. + 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. + 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 @@ -134,62 +134,65 @@ versioning will occur according to this standard. 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. + 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 + 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). + 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. + 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. +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 @@ -211,8 +214,8 @@ Issues, Pull Requests, and Branches - https://github.com/PlasmaPy/PlasmaPy-PLEPs/pull/8 -- `Semantic Versioning: Why You Should Be Using - It `__ +- `Semantic Versioning: Why You Should Be Using It + `__ - A `critique of semantic versioning that proposes “romantic versioning” `__ @@ -247,4 +250,7 @@ versioning. Some options include: Decision Rationale ------------------ -*This PLEP is in preparation and has not been decided upon.* +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.