Release branch and tag name convention

[matsbn]

I would like to very soon make a persistent release branch for the BLOM version to be used in the upcoming NorESM2 release. Then a tag of this release branch will be used in the Externals.cfg of NorESM. Since release branches and tags will persist, it can be good to choose a sensible naming convention. My suggestion is that we call release branches for "release-<major version>.<minor version>" and tags for "v<major version>.<minor version>.<patch>". Then the next release will be maintained in branch "release-1.0" and tagged "v1.0.0". Maintenance and bug fixes or documentation enhancements of BLOM1.0 will then happen in "release-1.0" branch and tagged "v1.0.1", "v1.0.2" and so on. Changes in a release branch should not change answers of existing configurations. When it is time to release a new answer-changing version or significant new functionality, I think a new release branch, say "release-1.1", should be made. I am not sure about when to increment the major version number, but that we can leave for later discussions (it could be as infrequent as to coincide with CMIP phases).

If you have some comments/suggestions to this branch and tag name convention, it would be great to discuss it in this thread.

[TomasTorsvik]

I think this looks very sensible. I think there should be a relatively low barrier for "minor version" increments, i.e. some collection of bug fixes and functionality tweaks collected over time should be sufficient. For the "major releases" it would be good to make a plan in advance for what we want to include, perhaps using the "project" and "milestone" functionality in gitHub.

[tylov]

I think this is a sensible and common way to version the software. There is an overview over various version number schemes at https://en.wikipedia.org/wiki/Software_versioning

It is worth thinking about what the idea about the numbering scheme is: does it reflect compability series or development phases? (or both). As described in the Wiki, some use a finer resolution x.y.s.p, where s=stage (alpha=0, beta=1, rc=2, final=3). May be overkill (it does require extra effort to maintain this scheme - when to change from the various stages), but worth considering.

Major version number: Many softwares keeps stable input/output data formats, or provide automatic backward compability within each major version number. On major number bumps, data formats may change, but normally one should create a separate convertion tools or describe how to convert old format to the new version.
Often though, major version number is changed when an big/important new feature is introduced, (that may or may not also change data formats).

[tylov]

Just another comment on data format compability. I am not sure how important backward compability is, i.e. for reproducability you want to use a specific version with a specific dataset. But I suppose for reanalysis, backward compability is important. Also note that some software even support forward compability, e.g. .docx, xlsx, pptx formats was introduced in Office 2007, but Microsoft provided a plugin that worked for Office 2000, XP and 2003, to transparently read/save those formats.

[matsbn]

Thanks for useful comments! It is indeed challenging to choose the level of version granularity suitable for this repo. If we find it useful with prereleases, I would maybe prefer tags of the e.g. release-1.1 branch like v1.1-alpha0, v1.1-beta1, v1.1-rc1 and then tag v1.1.0 as the first release of the 1.1 branch. These prereleases could be embedded in the numbering scheme as you mention, @tylov, but I find it less intuitive. I agree with you @TomasTorsvik, that there should be a relatively low barrier for "minor version" increments.

After thinking some more about it, I am still in favour of a workflow inspired by "trunk-based development". Then development happening in feature branches are merged to master as soon as possible. To maintain a master in good working order, a good testing procedure should be in place and this must be prioritised. I have revised a git workflow I presented some time back with the updated versioning: