Semantic versioning

author	date	tags
PE	2023-01-08	cubi, internal, convention, rule, policy, standard

Meaningful code versioning

The CUBI adheres to the principles of "semantic versioning" to indicate the version of a piece of code or of an entire code base (i.e., of the entire repository). Briefly, that implies the following:

• the data type of the version information in the code is always "string"
  • version 1 could be an integer, version 1.0 could still be a float, but 1.0.0 can only be a string
  • trailing zeros can be omitted, but remember that explicit is better than implicit
  • hence, version 1 is identical to version 1.0 is identical to version 1.0.0
• the three components of a version string are identified as: MAJOR.MINOR.PATCH
  • major: changes incompatible to prior versions of the same code base
  • minor: changes extending the functionality of the code base
  • patch: bug fixes or documentation updates
• the prefix "v" can be omitted if the context is clear
  • in code, a line like __version__ = "1.0.1" is sufficiently clear
  • in text, the prefix is commonly used, e.g., "we used release v1.0.1" or "this feature was introduced in v2.0.3"
• additional qualifiers can be used to indicate special conditions
  • these qualifiers must always be separated by a dash/minus from the numeric version information
  • dev: for releases made from the "dev" branch, e.g., v1.0.0-dev
  • dirty: if the code at hand refers to a specific version of another code base, but includes changes relative to that version, e.g., v2.0.4-dirty
    • for example, the code of a workflow template might have been changed in the current code to work around certain issues
    • note that this is an exceptional case that needs justification; normally, the other code base should be updated leading to a new release
  • ptyp: should be used rarely, but for releases made the "prototype" branch, the qualifier "ptyp" (= prototype) can be used, e.g., v0.1.9-ptyp
• if the version information is manually updated, the increase of just the number should be a commit of its own (= commit does not contain any code/doc changes)

What are "incompatible" changes?

In the context of a workflow, incompatible changes mandating an increase in the MAJOR version number can be characterized as follows (non-exhaustive list):

• functionality is removed from the code base
• the semantics of existing features are changed, e.g., a function now returns A and B instead of just A
• software tools that are part of the workflow are updated to fix errors (the workflow output changes relative to prior verions)
  • note that an update of the workflow environment, e.g., pertaining to a workflow manager such as Snakemake, may only qualify as a minor version update if the output of the workflow is not affected

Version information in Python code

The version of the Python interpreter in use can be accessed as follows:

>>> import sys
>>> sys.version_info
sys.version_info(major=3, minor=9, micro=15, releaselevel='final', serial=0)
>>> sys.version_info.major
3

The default Conda environments of the CUBI that at least partially target a Python development should include the semver package to deal with parsing version information from more complex strings.