Amend PLEP 5 with updated versioning scheme

[namurphy]

PLEP 5 currently specifies that PlasmaPy uses semantic versioning (SemVer). SemVer requires that (after the 1.0.0 release) any backward incompatible changes result in an incremented major version number. This is not so practical for a scientific software package that has a continual, "perpetual beta" development model such that there are likely to be some backward incompatible changes needed during every non-patch release. (I believe there were some extensive discussions about this in SunPy.)

We haven't reached consensus, but some options and an incomplete tradeoff analysis.

1. 0️⃣ Keep using 0.y.z versioning for the time being
   • Pros: Emphasizes that we are still in the development phase. Consistency with prior versions. Consistency with packages like Astropy, NumPy, SciPy, matplotlib, xarray, etc. We can procrastinate making this decision for longer than we have been 😬.
   • Cons: Keeping with this scheme for a long time will continue to imply package instability & immaturity. Won't be able to tell how old a version is just by the version number.
2. 📆 Switch the calendar based versioning (e.g., PyCharm has versions like 2021.1.2 where 1 refers to the release number in a given year) now or at some point later.
   • Pros: Lets people know how old their version of PlasmaPy is. Consistency with software like dask, Ubuntu, & PyCharm. Easy to understand just from reading it. Would let users know in case there is any time-sensitive functionality (i.e. if a version is released before an experiment or diagnostic began operations).
   • Cons: Inconsistency with prior versions. Inconsistency with most of the packages that we depend on. Won't be able to tell how mature a package is just by the version number. Would need to be a permanent change to preserve monotonicity.
3. 🔢 Switch to a versioning scheme like SunPy's where the major version number is incremented for every long-term support release.
   • Pros: Consistency with prior version scheme. Consistency with packages like Astropy, NumPy, SciPy, matplotlib, xarray, etc. LTS releases are predictable and built into the schedule. Would be able to switch to calendar based versioning later on.
   • Cons: Won't be able to tell how old a version is just by the version number. Won't be able to tell a release is LTS just from the version number without being familiar with how these versioning schemes usually work.

If there are any pros and cons that this is missing, please post below.

[namurphy]

My own preference is for option 3 because I place a lot of importance on consistency with the packages that we depend on or are likely to use.

To get an idea of how much date-based versioning is used in the scientific Python ecosystem, I checked my own conda environment for PlasmaPy development (which includes some packages that we don't depend on but might in the future). Out of the 338 packages I have installed, 16 (≈4.7%) have versions that start with either 20 or 21.

Interestingly, libedit has a version of 3.1.20191231, which combines the two different versioning schemes. Or maybe they've had ∼10⁷ bug fix releases. I give it a 50% chance either way.

$ conda list | wc -l  # number of packages I have installed plus 3 header lines
341
$ conda list | grep "\ 20\|\ 21" | wc -l  # number of packages with versions that start with 20 or 21 
16
$ conda list | grep "\ 20\|\ 21"
argon2-cffi               20.1.0           py37h5e8e339_2    conda-forge
attrs                     21.2.0             pyhd8ed1ab_0    conda-forge
black                     21.7b0             pyhd8ed1ab_0    conda-forge
ca-certificates           2021.5.30            ha878542_0    conda-forge
certifi                   2021.5.30        py37h89c1867_0    conda-forge
dask-core                 2021.7.2           pyhd8ed1ab_0    conda-forge
fsspec                    2021.7.0           pyhd8ed1ab_0    conda-forge
imagecodecs               2021.7.30        py37hfe5a812_0    conda-forge
incremental               21.3.0                   pypi_0    pypi
packaging                 21.0               pyhd8ed1ab_0    conda-forge
pip                       21.2.3             pyhd8ed1ab_0    conda-forge
pyopenssl                 20.0.1             pyhd8ed1ab_0    conda-forge
pytz                      2021.1             pyhd8ed1ab_0    conda-forge
regex                     2021.8.3         py37h5e8e339_0    conda-forge
tifffile                  2021.8.8           pyhd8ed1ab_0    conda-forge
virtualenv                20.4.0                   pypi_0    pypi

[namurphy]

Right now I'm experiencing another reason for date-based versioning. I've been trying to get versions of Fortran libraries working together with code that hasn't been updated in a few years, and the modern versions of libraries are not linking correctly. It would have been helpful if the versions were date-based so that I could find ones that were all from ~2015.

This would be a strong point in favor of date-based versioning in the fortraniverse, in particular since there's no one place to look up release dates and I don't know of any dependency resolvers. I'd say it's a minor point in favor of date-based versioning in the pythoniverse since we can find package release dates on PyPI quickly, and we have a whole bunch of good dependency resolvers in pip and conda.

[namurphy]

Another point in favor of date-based versioning (made by @rocco8773, I think?) is that the changes between v0.(n-1).* and v0.n.* are probably going to be comparable in magnitude to the changes between v0.n.* and v1.0.0. That is to say...there isn't going to be a clear marker for when we get to v1.0.0.

[namurphy]

One of the alternatives discussed above is having n.0.* be long-term-support (LTS) releases, for $n ∈ ℕ$. However, there isn't currently a demand for LTS releases, and it's unlikely we'll do one in the next couple of years until we build up the contributor base.

[namurphy]

Date based versioning was also helpful in https://github.com/PlasmaPy/PlasmaPy/issues/1680 where I was trying to quickly figure out when a release of pip was.

Given the tradeoffs above and my last few comments, I'm now in support of changing to date-based versioning, perhaps for our first release in 2023 if we can edit PLEP 5 by then.

[StanczakDominik]

When we do that, we're absolutely doing a blog post along the lines of "PlasmaPy will never reach 1.0".