Versioning Guide

Generally all development work leading to a new release goes into the develop branch (using a feature branch and pull-request model). Once the develop branch is ready for a release (usually because an instrument is starting a science data run), it gets merged into main, at which point it is tagged according to the version format guidelines below.

The version tagging format follows this style:

YYYY.MM[.N][revision]

Where YYYY is the year, MM is the month with a leading zero, N is used if more than one full release happens in that month and starts at 1 (with zero for the first release implied). The revision is for a hot fix applied to a specific release, and is a letter, starting with 'a'.

For example the first release in Mar of 2022 would be 2022.03, the second would be 2022.03.1, and a hot fix to 2022.03 would be 2022.03a.

Full release tags should always be made against the main branch. For hot fix releases, a new branch with the name [version]_hotfix should be created and used for all hot fixes. So in the example above 2022.03 would get a branch named 2022.03_hotfix and tags on that branch of 2022.03a, 2022.03b, etc. All hot fixes should pushed both to hot fix branch and develop so they are merged into all future full releases.

Generally releases will occur when a telescope or subsystem using kotekan goes into an science observing mode requiring changes currently only in the develop branch. For example if telescope X needs feature A in develop, then all of develop will be merged into main and a release will be generated. This means that features in develop for any system should not be incomplete, in the sense that they cannot break existing functionality pending another unmerged change, and also that the feature A shouldn’t break the functionality of telescope Y. That is partly enforced by requiring all unit tests to pass priory to merging feature branches into develop, and by careful code reviews.

Once an instrument is running a given version, if a problem is found that only impacts that instrument, then instead of moving to the latest version, they can opt to generate a hot fix release. For example if telescope X is running version 2022.03 and finds a bug, but wants to stay on that version for code stability during a science run, then the bug can be fixed with a hot fix release.

The goal of this design is to maintain only one primary branch which all instruments can use, and that instruments will generally strive to run the latest version available. While also allowing for instruments to opt to stay on a given release version for an extended period of time, where code stability is more desirable than being upto date. However, using hot fix branches to add new features as “instrument specific branches” is strongly discouraged, as this will lead to code fragmentation and eventually prevent older systems from making use of features in newer versions of the framework. All instruments should strive to be upto date with the latest code versions on some cadence, even if it is fairly slow (e.g. yearly for well established systems). Developers for new instruments should take care not to break existing functionality, or if needed, do so in a well documented way giving the older systems a path to upgrade. For example an API could change its signature and support new features, but must still provide the original functionality with minimal changes for the older instrument to update.