Versioning conventions

[josiahjohnston]

This post assumes you have read Choosing a Versioning Scheme, which recommends Semantic Versioning.

Right now we are in beta phase 2.0.0b_X_. We'll shift to release candidate 2.0.0rc_X_ around the time the paper is being reviewed, and a full release 2.0.0 sometime after the paper is published. Subsequently, we'll need to iterate version numbers every time we push to PyPi or Anaconda.

Semantic Versioning Summary

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Ideally, every validated pull request to the main branch would increment the version number, and there is probably some software available to help automate that. Minimally, we will need to manually increment the version number whenever we introduce a change that requires reformatting/upgrading the input files. Typically, those changes would increment MINOR, but we are currently in beta stage, so we are incrementing the beta suffix

We also have an option to use developer versions *2.0.0dev_X_ for playing around with things that are primarily meant for other developers, but I don't know if that will offer any benefit over feature-specific git branches.

Does anyone have questions, comments, amendments or counter-proposals?

[mfripp]

This is surprisingly tricky to manage correctly. I would suggest that the minor version number on the master branch use a unique commit number that constantly moves forward (similar to Pyomo). This could be generated via git rev-list --count --first-parent master. We just have to remember to run that command, add 1, store the new number in setup.py and then commit setup.py to the current branch before each pull request is merged. (Alternatively, we could store the minor version number in a text file and read that from setup.py; but we'll still need to update that file before merging each pull request.) Then for any "public" release, we can tag the relevant commit with the matching version number.

I also have to contend with version numbering for customized branches which I occasionally share with collaborators. I think the best I can do there is to use the version number from the point where each branch departed from master. The semantic versioning system is meant for linear releases and can't really be mapped onto a branching tree.

[josiahjohnston]

Did we resolve this in our weekly conference calls and email exchanges, or did I just imagine that we had settled on the semantic versioning method? I seem to remember us being ok with semi-manually incrementing the patch/minor version numbers for now when we push to PyPi, and probably writing/finding tools to automate some of that eventually. The decision of whether a version iterates the patch or minor number can't be automated and will rely on human judgement of whether we are fixing a bug or adding features.

I don't remember resolving the branching issue. Matthias, you are totally right that versioning is meant for linear releases. For branches, do you need a full versioning scheme or will a git reference (repo URI+hash) be sufficient? Versioning seems more important for wide user bases with long-lived code bases, whereas the customized branches you describe may have small enough user bases and short enough lifetimes that you don't need formal versioning. If your branches really do need formal versions, then the cleanest solution may be to treat their versions as permanent forks that start entirely new version counters from 0 in a new namespace. I guess you could do a non-standard convention of adding another suffix (2.0.0.foo1), but non-standard suffixes (anything besides a, b & rc I think) may not play well with version parsing tools and comparison operators (<=, etc).

[bmaluenda]

I too am under the impression that we agreed on using the semantic versioning method and manually incrementing the patch and minor version numbers. Though, I'm not sure if we agreed on manually incrementing patch numbers 1 on 1, or if we were going to use the commit number. The latter seems more practical, since it references a commit that any user can check (although it does create longer version numbers).

Switch branches seem to be used only by few users for specific purposes, so version numbers shouldn't be a problem for them (speaking as a user of one of such branches).

[josiahjohnston]

Updates:

• We're making a best-effort to follow semantic versioning guidelines, although we aren't always sure what features seem significant enough to bump the minor version.
• We have some interest in automatically including a build suffix for development & pre-release branches, but have not reached consensus on pull request Precise versioning with local branches #118 . For releases that are tagged as a specific version, the version would look like 2.0.5. Installations from commits not tagged as a release would have versions like 2.0.5+0f21b73, where 2.0.5 is the last tagged release on that branch, and 0f21b73 is a git digest describing the specific commit. If the repository was modified without a git commit, it would have an additional suffix of +localmod.

For background on recommendations for versioning build releases and implementation of greater than and less than operators, see "point 10" of Semantic Versioning 2.0.0 and "local identifiers" in PEP 440.