Historically, the Network UPS Tools project release and interim iterations code base versions were identified by three or four numeric components, roughly following the Semantic Versioning (SEMVER) traditions, later codified as a formal standard at semver.org:
configure.ac file an AC_INIT macro, which
further generates variables like PACKAGE_VERSION, PACKAGE_URL and others
used (substituted) in the actual code base, often via nut_version.h file.
MAJOR.MINOR.PATCH triplet, which
was not strictly following the standard in that while the "major" part
did reflect architectural/design changes, and "minor" part reflected some
significant development milestones or API changes, the "patch" part did
not correspond to post-release fixes but reflected iterative development,
of which releases were the better-reviewed snapshots. Such a triplet was
only spelled in AC_INIT for the commit tagged as that release.
Until NUT v2.6.x, the odd values of the MINOR component meant development
code trees, and even values meant the stable tree. This approach was
skipped (or effectively abandoned, as over a decade passed) with the
move to Git branches for development — as numerous NUT v2.7.x based
releases were produced, and development continued into NUT v2.8.x.
The project reserves an option to return to the even-odd cadence (and perhaps proper major-minor-patch versioning on stable tree) later.
AC_INIT macro argument like
MAJOR.MINOR.PATCH.1 to provide a fourth component — which is
logically "greater than" MAJOR.MINOR.PATCH for comparisons, so that
the developed version can formally be installed over a preceding
release (e.g. from custom testing packages).
This configuration with a single development version (.1) was not very
helpful for the faster pace of iterations, especially as the Git workflow
and pull requests were adopted as the way of iterating the NUT development.
This did not really help identify the build being tested by CI or reported
by a community member, nor quickly determine if one custom build is "newer"
than another (e.g. can be a recommended upgrade from the previously installed
snapshot to check if some bug was fixed).
Some experiments were done adding the git describe output to version
banners reported by programs. These provide the number of commits since
the most-recent known git tag, as well as the git hash of the NUT sources
involved. This made the builds better identifiable, but did not help
compare the feature branches and the main trunk of development: any code
committed after a release has its own count of commits since that tag,
this one number does not really suffice.
Since NUT v2.8.3, the definition which goes into AC_INIT and further into
the code was extended in a manner similar to what git describe produces,
but with added numbers after the common triplet of semantically versioned
numbers: X.Y.Z(.T(.B(-C+H(+R)))) or X.Y.Z(.T(.B(-R)))
Standard semver (used in releases):
Historically NUT did not diligently follow the standard semver triplet, primarily because a snapshot of trunk is tested and released, and work moves on with the PATCH part (rarely MINOR one) incremented; no actual patches are released to some sustaining track of an older release lineage. There were large re-designs that got MAJOR up to 2, though.
X: MAJOR - incompatible API changes
Y: MINOR - major new features and/or API evolution
Z: PATCH - bug fixes (and new features like added drivers)
Extended semver (for snapshots of trunk):
Extended semver (for features branched off trunk):
The optional suffix (only for commits which are not git tags themselves)
is provided by git describe:
The pre-release information (if provided/known) would either follow the optional suffix detailed above, or it would be the suffix itself:
2.8.2.2878.1-2879+g882dd4b00+v2.8.3+rc6
The numeric part of NUT SEMVER definition mostly follows https://semver.org/ except that for development iterations the base version may have up to five dot-separated numeric components (SEMVER triplet for base release, and additional data described above). Unlike standard semver provisions for "pre-release versions" (separated by a minus sign after the triplet), which are "less than" that release for comparisons, the fourth and fifth components (if present) are "greater than" that release and any preceding development iterations made after it.
Helper script tools/gitlog2version.sh is used to determine the project
version from packager-provided override files (or equivalents provided by
make dist in a snapshot/release tarball), git metadata from the current
workspace, or built-in fallback defaults.
Occasionally there may be tagged pre-releases, which follow the standard
semver markup, like v2.8.0-rc3 (in git), however they would be converted
to NUT SEMVER here (as a number of commits since previous release) by default.
A special case, which can mostly be seen in CI builds, concerns shallow git
checkouts — when the currently built commit history is "grafted" (perhaps
down to there being only one commit in the whole git index), and we do not
know of any intersections with git tags or development trunk. In this case,
the script may not only fall back to a built-in version following a legacy
X.Y.Z.1 pattern for non-release builds (like 2.8.3.1), but would also
append a -0-g{HASH} suffix to the long values (VER5, VER50, DECS5,
DESC50) yielding e.g. 2.8.3.1.0-0+gb3f21f9 for a build from a shallow
git checkout of commit b3f21f9 of a code base which otherwise fell back
to 2.8.3.1 hard-coded in its copy of the script (bumped by a maintainer
as part of the release process).
The script can be controlled by environment variables, including some sourced
from configuration files. It identifies a number of data items, and reports
the one specified by NUT_VERSION_QUERY on stdout.
It does not currently have a query to report "everything" in a manner
that can be processed by eval in calling shell scripts (or Makefile rule
implementations).
Table 1. Environment variables that can be used for external configuration
Variable | Description | Example |
| Top source directory |
|
| Top build directory (defaults to |
|
| Set |
|
| Set |
|
| Usually sourced from either
‘${abs_top_builddir}/VERSION_DEFAULT` (if present)
or |
|
| If not provided by caller, or sourced files,
or defaulted with |
|
| Default website URL, extended for historic sub-sites for a release |
|
| Git branch name to use for calculation of
current codebase distance from main development (as known
in local workspace index); by default, the newest branch named
like |
|
| If |
|
| If |
|
Table 2. Intermediate variables in Git workspace processing
Variable | Description | Example (development and release) |
| Originates from |
|
| Nearest (annotated by default) tag preceding the |
|
| The |
|
| Commit count since the tag and hash of the |
|
| Full 5-component version, note we strip leading |
|
| Full 5-component version |
|
|
|
|
|
|
|
| Exactly three leading numeric components.
Either |
|
Table 3. Intermediate variables in default (non-git — tarball or forced) processing
Variable | Description | Example (development and release) |
| Processed from |
|
| Grows from |
|
| Constructed from |
|
| Decreases from |
|
| Constructed from |
|
| Empty, unless |
|
| Full 5-component version, |
|
| Constructed as |
|
|
|
|
| Constructed as |
|
| Empty (no known common commits with no trunk) |
|
| Exactly three leading numeric components.
Either |
|
| Optionally populated to construct |
|
| Constructed from |
|
| Constructed as |
|
The majority of identified values can be reported for debugging to stderr,
currently as a single line (wrapped for readability in the sample below):
:; ./tools/gitlog2version.sh SEMVER=2.8.2; TRUNK='master'; BASE='e9a48c9afeb4e06c758a3f4215977445c0f64780'; DESC='v2.8.2-2381+g1faa9945d' => TAG='v2.8.2' + SUFFIX='-2381+g1faa9945d' => VER5='2.8.2.2379.2' => VER50='2.8.2.2379.2' => DESC50='2.8.2.2379.2-2381+g1faa9945d'
Table 4. Values reported via NUT_VERSION_QUERY
| Description | Example (development and release) |
| Full 5-component version (concatenated with |
|
| 3-to-5 non-zero component version (concatenated with |
|
| Full 5-component version |
|
| 3-to-5 non-zero component version |
|
| Expanded variants of respective
reports, with leading zeroes padding up the initial
dot-separated numbers to |
|
| Exactly three leading numeric components |
|
|
|
|
|
|
|
| GIT: Nearest (annotated by default) tag preceding the |
|
| GIT: if the |
|
| GIT: Branch name used for calculation of current codebase distance from main development. DEFAULT: empty. |
|
| GIT: Commit count since the tag and hash of the |
|
| GIT: Constructed from |
|
| GIT: Newest common commit of development |
|
| Clarify the project website URL — particularly historically frozen snapshots made for releases |
|
| Used in |
|
| Used in maintainer rituals (requires git) to
update the |
|
default | Report |
|
To facilitate version comparisons of different NUT iterations in scripts, the "expanded variants" of the two versions can be requested. This pads each semver component (but not other numbers) with zeroes to a specified width (by default 6 digits):
:; NUT_VERSION_QUERY=VER5X \ NUT_VERSION_FORCED=3.14.159.2653.59-2712+gdeadbeef \ gitlog2version.sh 2>/dev/null 000003.000014.000159.002653.000059
If you map this as an e.g. tab-separated list of "expanded" and original
version strings, you can use the shell sort command to find the oldest
and newest builds, construct an ordered list for downloads, etc.
Keep in mind that you should not use those zero-padded component numbers
in shell math operations, as they would be considered octal numbers (and
possibly invalid ones, if they contain digits 8 or 9). You can revert
the operation with envvar toggle NUT_VERSION_STRIP_LEADING_ZEROES=true
(note it only impacts the leading dot-separated numbers semver part of the
string, but not any numbers in the suffix):
:; NUT_VERSION_QUERY=DESC5 \ NUT_VERSION_FORCED=3.014.00159.02653.05-002658+gdeadbeef+v01.002.0003 \ NUT_VERSION_STRIP_LEADING_ZEROES=true \ gitlog2version.sh 2>/dev/null 3.14.159.2653.5-002658+gdeadbeef+v01.002.0003
As a result of work on gitlog2version.sh, and specifically the next-level
problems of managing the data set of multiple NUT SEMVER strings (sorting,
comparisons, etc.), another helper script was born: the semver-compare.sh.
It contains the implementation of "expanded variants" of the versions and
"stripping leading zeroes" used above by the original gitlog2version.sh
script, as well as more features used by, for example, the Makefile.am
recipes for nut-website
which deal with sorted lists of NUT versions for the DDL page rendering
(reports about same device model which originated from different NUT releases).
Common options for scripted actions are (must be mentioned before the action):
{--width|-w} NUM
6).
{--min-components} NUM
Ensure there are at least so many components - add .0 in the end if
needed (NUT SEMVER default is 5 for expand action).
Not implemented yet for stripping extra zeroed components from a semver.
Actions which can be repeated on same command line include:
semver-compare.sh [OPTS] expand "SEMVER"
semver-compare.sh [OPTS] strip "SEMVER"
semver-compare.sh [OPTS] --sortable-expand "SEMVER"
sort by the first column).
semver-compare.sh [OPTS] --sortable-strip "SEMVER"
sort by the first column).
Actions which end the script execution include:
semver-compare.sh [OPTS] sort [-r] "SEMVER" "SEMVER"...
semver-compare.sh [OPTS] {test|[} "SEMVER1" {-gt|-ge|-lt|-le|-eq|=|==|-ne|!=|<>|<|<=|>|>=} "SEMVER2"
Shell-style syntax to compare two semver strings (via expanded variants).
Note that --min-components can play a role here (e.g. is 1.2.3 equal
to 1.2.3.0.0? You can specify whether and how many zeroes can be added
so it would be or not be equal).
If you would sort expanded semver strings yourself, be sure
to NOT mention the numeric sorting option — it misbehaves for strings
which do not look like exactly an integer or floating-point number.
For portability and non-regression, the functionality of both scripts is
extensively tested by tests/nut-driver-enumerator-test.sh in the NUT code
base.
Table 5. Values reported via NUT_VERSION_QUERY
Variable | Description | Example (development and release) |
| Argument to |
|
| Argument to |
|
| Derived from |
|
| Determined by |
|
| Determined by |
|
| Determined by |
|
| Determined by |
|
| Determined by |
|
| String determined by |
|
Table 6. Values encoded via include/nut_version.h, generated by include/Makefile.am
Variable | Description | Example (development and release) |
| Determined by default |
|
| Determined by |
|
| Determined by |
|
| Determined by |
|
NUT_VERSION_MACRO is used in common/common-nut_version.c and further
made known to all code base as a static string UPS_VERSION linked via
libcommon*.la internal libraries.
Method describe_NUT_VERSION_once() prepares the string which combines the
NUT_VERSION_MACRO with comments that it is either a release or a
(development iteration after $NUT_VERSION_SEMVER_MACRO), based on
the value of NUT_VERSION_IS_RELEASE.
It is used from a number of other methods, such as print_banner_once(),
nut_report_config_flags(), and so ends up in version reports of programs
via their help()/usage() methods.
suggest_doc_links() prepares a uniform bit of text for driver and
tool programs to report in their help()/usage() methods, to refer to
their manual page under the NUT_WEBSITE_BASE.
PACKAGE_VERSION,
PACKAGE_VERSION and NUT_WEBSITE_BASE as asciidoc attributes
when rendering HTML/PDF/man document formats.
NUT_WEBSITE_BASE is also substituted instead of literal
https://www.networkupstools.org/* which follows a home page: prefix
(so that the pages rendered for a release refer to the historic website).
Service manifests include references to documentation for the tools they wrap,
including published pages under the NUT_WEBSITE_BASE for the development or
historic variants of the NUT website.