What versioning scheme should we use?

[namurphy]

At some point we will need to decide on a versioning scheme. It'd probably be good to figure this out sooner rather than later so we can have as consistent a scheme as possible for the lifetime of the project. I looked into what other projects are doing, and ended up finding PEP 440 -- Version Identification and Dependency Specification which extensively describes a canonical format that is required in order for public releases to be compatible with setuptools and PyPI. I didn't read the whole thing as that page contains almost 10000 words, but the examples were helpful. I wrote up a draft versioning scheme below that is consistent with PEP 440 as something that we can start the discussion from, though I'm happy to change it. We could perhaps work towards a PLasmaPy Enhancement Proposal like APE-2 for Astropy that includes how we end up doing releases. Two things that are important are that the version is in a canonical format and that it behaves correctly:

>>> import re
>>> def is_canonical(version):    # appendix B of PEP 440...include as a unit test?
             return re.match(r'^([1-9]\d*!)?(0|[1-9]\d*)(\.(0|[1-9]\d*))*((a|b|rc)(0|[1-9]\d*))?(\.post(0|[1-9]\d*))?(\.dev(0|[1-9]\d*))?$', version) is not None
>>> is_canonical('0.0.1.dev1')
True
>>> is_canonical('0.0.1a1')
True
>>> from pkg_resources import parse_version
>>> parse_version('0.0.1a1') > parse_version('0.0.1.dev1')  # alpha release is newer than dev release
True

Here's my draft. Feedback and new ideas are appreciated, as this should be considered far from final!

The versioning scheme for PlasmaPy will be consistent with the canonical format described in PEP 440 in order for public versions to be compatible with setuptools and PyPI. Releases will use a [major].[minor].[micro] format with our first micro release being '0.0.1' and our first minor release being '0.1'. Development, alpha, beta, and release candidate versions will be appended by the pre-release tags '.dev', 'a', 'b', and 'rc', respectively, followed by an integer.

Here is a sample progression from older to newer versions:

0.0.1.dev1 # early development version prior to 0.0.1
0.0.1.dev2
0.0.1a1 # alpha version prior to 0.0.1
0.0.1a2
0.0.1b1 # beta version prior to 0.0.1
0.0.1b2
0.0.1 # micro release
0.1.dev1 # development version for first minor release
0.1a1 # alpha release prior to 0.1
0.1b1 # beta release prior to 0.1
0.1 # first minor release

The decision on when to change between development, alpha, beta, and release candidate versions will be made by the Code Development Committee with general community agreement. The trailing integer that follows pre-release tags should be incremented after appreciable changes to the code have accumulated in the development process.

[namurphy]

Astropy has development version tags like '2.0.dev18104' where the trailing number appears to be the number of the commit for that version. They are automating it using functions in git_helpers.py in astropy-helpers. Perhaps we can do the same!

[SolarDrew]

👍 I'm happy with this. On a similar note, we should look at the package-template and astropy-helpers packages, which help with a lot of this sort of thing, I believe.

[namurphy]

@SolarDrew - Yes, good idea!

For quick access:

• Astropy package-template
• astropy-helpers

[namurphy]

The discussion of issue #37 brought up a useful website on semantic versioning.

[namurphy]

Closing this because we're on the way to using semantic versioning.