OVIS LDMS Versioning

Versions

Modified Semantic Version

OVIS/LDMS roughly follows Semantic Versioning guidelines. The most notable exception is that the meanings of MAJOR, MINOR, and PATCH are somewhat different. Some examples of our release versions:

4.3.8
4.3.8-rc.2

Note also that build metadata is currently appended with a . rather than a +.

Version strings necessarily differ from the Modified Semantic Versioning format in various contexts, but wherever possible the differences will follow well-defined rules making them easy for humans to match together, and easy to programmatically automate.

Versions in Git Release Tags

Git release tags must always be annotated tags (and optionally may be signed).

Git release tags are just the Modified Semantic Version with a common prefix:

v<Modified Semantic Version>

For instance:

v4.4.3

NOTE: In the past the prefix was "OVIS-".

Build metadata is automatically generated, and thus should never appear in the git tag.

Versions in the Build System (i.e. autoconf/make)

In the source code of OVIS/LDMS, the version is automatically generated by the script git-version-gen. Making sure that the version is correctly and automatically set under all scenarios is trickier than it might seem, and git-version-gen handles most of the heavy lifting.

git-version-gen is called using m4_esyscmd under AC_INIT of configure.ac. When run in a git working directory, git-version-gen uses "git describe" to get the version from the most recent annotated tag with the proper format. It also sometimes appends additional build metadata when the working directory is dirty, or the most recent annotated tag does not match the currently checked out commit.

NOTE: git-version-gen ignores branches and light-weight tags, it only looks for annotated tags.

NOTE: autoconf must be re-run (and code recompiled) to pick up update the version after any changes in the git working directory. This is the one unfortunate consequence of autoconf's design as related to version strings. We might in the future look at autoconf's GNUmakefile, which has a complicated rule to force autoreconf for dist-related targets when the version is not up to date.

Versions in RPM packages

RPM packages are one area where the version string must be changed from the the Modified Semantic Version.

RPM packages have two version-like fields, one named "Version", and the other named "Release". For the most part (at least as of RHEL8), the OVIS/LDMS version should only appear in Version field. The Release field should be left to the use of the end packager, denoting only changes to the spec file (and resulting build) rather than changes to the OVIS/LDMS source code.

Hyphens, '-' are not permitted in the RPM Version field. This necessitates some conversion of the OVIS/LDMS Modified Semantic Version string to allow it to be used with RPM packages. Fedora's Versioning Guidelines give us some guidance on how to do this correctly. In particular, see the section Handling non-sorting versions with tilde, dot, and caret.

Some guidelines for converting the OVIS/LDMS version into an RPM Version string are:

1. If a pre-release substring is present, e.g. "-rc.1", convert the leading hyphen('-') into a tilde('~').
2. If a build metadata substring is is present, e.g. ".180-32d52", convert the leading dot('.') into a caret('^').
3. Convert any remaining, prohibited hyphens('-') into underscores('_').

For instance, the following OVIS/LDMS versions:

4.3.11.180-32d52
4.3.12-rc.1
4.3.12.rc.1.11-4fec2

would respectively become the following RPM Version strings:

4.3.11^180_32d52
4.3.12~rc.1
4.3.12~rc.1^11_4fec2

Third Party Versions

Sometimes a third party (some organization rather than the upstream ovis-hpc project) needs to release a modified version of OVIS/LDMS, and it is best to create a distinctive tag that makes the difference obvious. For instance, the TOSS distribution (a RHEL-derived HPC distribution) has its own releases of OVIS/LDMS. Their changes are usually minor, and include adding RPM spec files, backported fixes, or minor improvements.

The llnl/ovis looks for the most recent release tag, and then creates its annotated tag that cannot conflict with upstream tags by appending a particular pattern to the upstream tag.

For instance, if the most recent tag from upstream is:

v4.4.3

The TOSS tags might look like:

v4.4.3_1toss
v4.4.3_2toss
etc.

By making these annotated tags in git, the normal OVIS/LDMS build system using git-version-gen will incorporate the third party TOSS-specific tags automatically.

Branches

The Main Branch

The main development branch of the OVIS/LDMS git repository is named OVIS-4.

From time to time release branches will be necessary to update older releases of OVIS/LDMS.

NOTE: In the future, the "OVIS-4" branch should be renamed to "main" to be more consistent with common practice.

Release Branches

Release branches intended to generate releases should follow the following general pattern:

b<major version>.<minor version>

For instance:

b4.4

The expectation for a branch named "b4.4" is that all future versioned releases of the pattern 4.4.* will take place on this release branch.