Versioning
The version is derived from Git by the setuptools_scm
Python module and follows PEP0440’s version identification
and dependency specification for final and pre releases.
Classification
The items below denote how stable, pre-release, and unstable versions are classified through version strings.
- (stable) release: A git-tag following the
X.Y.Z
semver format is considered a stable, release version.
# Format:
# {tag}
# X.Y.Z
# X - Major
# Y - Minor
# Z - Micro (a.k.a. patch)
0.1.2
- (stable) post-release: A git-tag following the
X.Y.Z.postN
(whereN
is an integer), indicates a post-release. These are seldom used, and are strictly for handling documentation, packaging, or other meta updates after a release tag was already created where it isn’t warranted to publish an entirely new release.
# Format:
# {tag}
# X.Y.Z.postN
# X - Major
# Y - Minor
# Z - Micro (a.k.a. patch)
# Z - Post release [1-9]+
0.1.2.post1
NOTE
X.Y.Z.post0
is equivalent toX.Y.Z
,post0
indicates the first release.
- (unstable) pre-release: A git-tag with an
a
(lpha),b
(eta), orr
(elease)c
(andidate) annotation and an identification numberN
denotes a pre-release/preview.
For
canu
, these are sometimes created before an official release (e.g. 1.7.0a1 might exist before 1.7.0 is released). Additionally the beta and release candidate tags may be skipped. Whether an alpha, beta, or release candidate pre-release is taken is entirely up to thecanu
release management team.
# Format:
# {tag}[{a|b|rc}N]
0.1.2a1
0.1.2b1
0.1.2rc1
-
(unstable) development: Development builds auto-increment the micro version (the
Z
inX.Y.Z
) or pre-release version (theN
inX.Y.Z{[a|b|rc]N}
), and then append a suffix based on whether the working directory was clean, dirty, or mixed.- clean: When the version shows an appended
devN+{scm_letter}{revision_short_hash}
, that means there have been commits made since the previous git-tag.
- clean: When the version shows an appended
# Format:
# {next_version}.dev{distance}+{scm_letter}{revision_short_hash}
# If the previous git-tag was 0.1.2:
0.1.3.dev4+g818da8a
# If the previous get-tag was a pre-release of 0.1.3a1:
0.1.3a2.dev4+g818da8a
* ***dirty*** When the version shows an appended `.d{YYYYMMDD}` datestamp, that means there were modified/uncommitted changes in the working directory when the application was built.
# Format:
# {next_version}.d(datestamp}
# If the previous git-tag was 0.1.2:
0.1.3.d20230123
# If the previous get-tag was a pre-release of 0.1.3a1:
0.1.2a2.d20230123
* ***mixed*** When the version shows a development tag with an appended datestamp, this means commits have been made but there were uncommitted changes present in the working directory when the application was built.
# Format:
# {next_Version}.dev{distance}+{scm_letter}{revision_short_hash}.d{datestamp}
# If the previous git-tag was 0.1.2:
0.1.3.dev3+g3071655.d20230123
# If the previous get-tag was a pre-release of 0.1.3a1:
0.1.3a2.dev3+g3071655.d20230123
Configuration
The setuptools_scm
module is configured by pyproject.toml
.
For more information regarding configuration of setuptools_scm
, see version number construction.