The Easter Bug hunt is over, release NUT v2.8.3 finally

Signed-off-by: Jim Klimov <[email protected]>

Author: jimklimov

common/common.c

@@ -623,7 +623,10 @@ const char *describe_NUT_VERSION_once(void)
 	if (1 < snprintf(buf, sizeof(buf),
 		"%s %s%s%s",
 		NUT_VERSION_MACRO,
-		NUT_VERSION_IS_RELEASE ? "release" : "(development iteration after ",
+		NUT_VERSION_IS_RELEASE ? "release" :
+			(NUT_VERSION_IS_PRERELEASE
+			 ? "(pre-release iteration of "
+			 : "(development iteration after "),
 		NUT_VERSION_IS_RELEASE ? "" : NUT_VERSION_SEMVER_MACRO,
 		NUT_VERSION_IS_RELEASE ? "" : ")"
 	)) {

configure.ac

@@ -51,12 +51,20 @@ NUT_SOURCE_GITREV="`NUT_VERSION_QUERY=DESC50 "${srcdir}/tools/gitlog2version.sh"
 
 dnl A true/false (literally) response that can be used for prettier messages
 dnl emitted by NUT code.
-NUT_SOURCE_GITREV_IS_RELEASE="`NUT_VERSION_QUERY=IS_RELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null`"
-AS_IF([$NUT_SOURCE_GITREV_IS_RELEASE], [NUT_SOURCE_GITREV_DEVREL="release"], [NUT_SOURCE_GITREV_DEVREL="development iteration"])
+NUT_SOURCE_GITREV_IS_RELEASE="`NUT_VERSION_QUERY=IS_RELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`"
+NUT_SOURCE_GITREV_IS_PRERELEASE="`NUT_VERSION_QUERY=IS_PRERELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`"
+
+AS_IF([$NUT_SOURCE_GITREV_IS_RELEASE], [NUT_SOURCE_GITREV_DEVREL="release"], [
+    AS_IF([$NUT_SOURCE_GITREV_IS_PRERELEASE], [NUT_SOURCE_GITREV_DEVREL="pre-release"],
+        [NUT_SOURCE_GITREV_DEVREL="development iteration"])
+])
 
 dnl Semantic version of most-recent NUT release this code is derived from.
 dnl It may equal the NUT_SOURCE_GITREV and NUT_SOURCE_GITREV_NUMERIC, but
-dnl this situation is only expected if NUT_SOURCE_GITREV_IS_RELEASE==true.
+dnl this situation is only expected if NUT_SOURCE_GITREV_IS_RELEASE==true;
+dnl for a pre-release it may differ from even the base NUT_VERSION numbers
+dnl (e.g. a commit tagged as 2.8.3-rc5 can have its own NUT_VERSION based
+dnl on 2.8.2-something, but is assumed as a pre-release for 2.8.3 SEMVER).
 NUT_SOURCE_GITREV_SEMVER="`NUT_VERSION_QUERY=SEMVER "${srcdir}/tools/gitlog2version.sh" 2>/dev/null`"
 
 dnl Gitrev-based build identifier which can be used for e.g. PyPI uploads:
@@ -5513,6 +5521,7 @@ AC_SUBST(NUT_NETVERSION)
 AC_SUBST(FORCE_NUT_VERSION)
 AC_SUBST(NUT_SOURCE_GITREV)
 AC_SUBST(NUT_SOURCE_GITREV_IS_RELEASE)
+AC_SUBST(NUT_SOURCE_GITREV_IS_PRERELEASE)
 AC_SUBST(NUT_SOURCE_GITREV_SEMVER)
 AC_SUBST(NUT_SOURCE_GITREV_NUMERIC)
 AC_SUBST(NUT_WEBSITE_BASE)

docs/maintainer-guide.txt

@@ -170,13 +170,46 @@ symbol names and API versions, similar to what `GNUC` or `SUNW` libraries do.
    file (DO NOT add them to git to avoid confusion later, or revert any such
    addition after the release -- still has a chance to confuse e.g. branches
    made from release tag later):
+*** Automation was introduced to help maintain these files, e.g.:
 +
 ----
+# Current commit MUST be git-tagged for *-(rc|alpha|beta) for magic to work:
+:; git tag v2.8.3-rc7
+
+:; NUT_VERSION_QUERY="UPDATE_FILE_GIT_RELEASE" ./tools/gitlog2version.sh
+SEMVER=2.8.3; TRUNK='upstream/master'; BASE='735451f1f21556f2a7b8443053e8962c2184239f';
+DESC='v2.8.2-2881+gbdade6241' => TAG='v2.8.2' + SUFFIX='-2881+gbdade6241+v2.8.3+rc7'
+ => VER5='2.8.2.2878.3' => DESC5='2.8.2.2878.3-2881+gbdade6241+v2.8.3+rc7'
+ => VER50='2.8.2.2878.3' => DESC50='2.8.2.2878.3-2881+gbdade6241+v2.8.3+rc7'
+
+# Note it assigns SEMVER from the pre-release tag, but other git info from
+# real git-describe details
+
+# You can verify current contents of these files with:
+:; grep . VER*
+VERSION_FORCED:NUT_VERSION_FORCED='2.8.2.2878.3-2881+gbdade6241+v2.8.3+rc7'
+VERSION_FORCED_SEMVER:NUT_VERSION_FORCED_SEMVER='2.8.3'
+----
+*** An older, possibly more reliable, way would go like this:
++
+----
+# Do not let them be easily deleted by e.g. `git clean -fdX` while you
+# would inevitably iterate the release attempts - keep in a subdir, and
+# juggle hardlinks (so they are archived into the tarball as real files):
+:; rm -rf .relver
+:; mkdir -p .relver
+
 # Generally may be the nuanced NUT SEMVER; is a triplet for releases
-:; echo 'NUT_VERSION_FORCED="2.8.3"' > VERSION_FORCED
+# or suffixed for release candidates
+:; echo 'NUT_VERSION_FORCED="2.8.3"' > .relver/VERSION_FORCED
+:; echo 'NUT_VERSION_FORCED="2.8.3-rc1"' > .relver/VERSION_FORCED
 
 # Should always be a triplet
-:; echo 'NUT_VERSION_FORCED_SEMVER="2.8.3"' > VERSION_FORCED_SEMVER
+:; echo 'NUT_VERSION_FORCED_SEMVER="2.8.3"' > .relver/VERSION_FORCED_SEMVER
+
+# Do not let them be easily lost; later you can just re-create these links
+# if file names in your top_srcdir are removed:
+:; ln .relver/* .
 ----
 *** Note that since NUT v2.8.3 this script dictates the version propagated by
     the `configure` script, so direct changes of `AC_INIT` there are no longer

docs/nut-versioning.adoc

@@ -54,7 +54,7 @@ Current NUT SEMVER definition
 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+gHASH)))`
+numbers: `X.Y.Z(.T(.B(-C+H(+R))))` or `X.Y.Z(.T(.B(-R)))`
 
 * Standard semver (used in releases):
 +
@@ -76,7 +76,15 @@ The optional suffix (only for commits which are not git tags themselves)
 is provided by `git describe`:
 
 * C: Commits on branch since previous release tag
-* H: Git hash (prefixed by `g` character) of the described commit
+* H: (Short) Git hash (prefixed by "g" character) of the described commit
+
+The pre-release information (if provided/known) would either follow the
+optional suffix detailed above, or it would be the suffix itself:
+
+* R: If this commit has a non-release tag, it can be optionally reported
+     so we know that a commit some '1234' iterations after release 'N' is
+     also a release candidate for 'N+1'. Note that any dash in that tag value
+     will be replaced by a plus, e.g. `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
@@ -118,7 +126,8 @@ implementations).
 			  may be just a triplet) to this value and enforce
 			  `NUT_VERSION_PREFER_GIT=false`. Usually sourced
 			  from `${abs_top_srcdir}/VERSION_FORCED` (if present)
-			| `2.8.3.2379`
+			| `2.8.2.2379` `2.8.3-rc3`
+			  `2.8.2.2878.3-2881+g45029249f+v2.8.3+rc6`
 |`NUT_VERSION_FORCED_SEMVER`	| Set `SEMVER` (exactly a triplet) to this value
 			  regardless of `NUT_VERSION_PREFER_GIT` setting. Usually
 			  sourced from `${abs_top_srcdir}/VERSION_FORCED_SEMVER`
@@ -210,18 +219,27 @@ implementations).
 			  numeric components as needed or dropping extras, to have
 			  *exactly 3* of them
 			| `2.8.0`
-|`VER5` and `DESC5`	| Full 5-component version, `NUT_VERSION_DEFAULT5`
+|`SUFFIX`		| Empty, unless `NUT_VERSION_DEFAULT` had a suffix
+			  for pre-release information roughly matching the
+			  `-(rc|alpha|beta)[0-9]*` regular expression
+			| `""` `-rc6`
+|`VER5`			| Full 5-component version, `NUT_VERSION_DEFAULT5`
 			| `2.8.2.2379.2`
-|`VER50` and `DESC50`	| `NUT_VERSION_DEFAULT` as provided by caller or
+|`DESC5`		| Constructed as `${VER5}${SUFFIX}`
+			| `2.8.2.2379.2` `2.8.3.0.0-rc6`
+|`VER50`		| `NUT_VERSION_DEFAULT` as provided by caller or
 			  defaulted, may be with or without trailing `.0` in fifth or
 			  fourth components
 			| `2.8.2.1`
-|`BASE`	| Empty (no known common commits with no trunk)	| `""`
-|`SEMVER`	| Exactly three leading numeric components.
+|`DESC50`		| Constructed as `${VER50}${SUFFIX}`
+			| `2.8.2.1` `2.8.3-rc6`
+|`BASE`			| Empty (no known common commits with no trunk)	| `""`
+|`SEMVER`		| Exactly three leading numeric components.
 			  Either `NUT_VERSION_FORCED_SEMVER` (if provided by caller or
 			  configuration files), or `NUT_VERSION_DEFAULT3` (see above)
 			| `2.8.0`
-|`TAG`	| Constructed as `v${NUT_VERSION_DEFAULT3}`	| `v2.8.0`
+|`TAG`			| Constructed as `v${NUT_VERSION_DEFAULT3}${SUFFIX}`
+			| `v2.8.0` `v2.8.3-rc6`
 |=========================================================================
 
 The majority of identified values can be reported for debugging to `stderr`,
@@ -260,16 +278,40 @@ DESC='v2.8.2-2381+g1faa9945d'
 |`IS_RELEASE`	| `true` if `SEMVER`==`VER50`, `false` otherwise
 			| * dev: `false`
 			  * rel: `true`
+|`IS_PRERELEASE`	| `true` if `SUFFIX_PRERELEASE` is not empty, `false` otherwise
+			| * dev: `false`
+			  * rel/RC: `true`
 |`TAG`	| GIT: Nearest (annotated by default) tag preceding the `HEAD` in history.
 		  DEFAULT: Constructed from `SEMVER`
 		| `v2.8.2`
+|`TAG_PRERELEASE`	| GIT: if the `HEAD` itself has a tag matching
+		  the `-(rc|alpha|beta)[0-9]*` regular expression.
+		  DEFAULT: Constructed from `NUT_VERSION_DEFAULT3`
+		  and `SUFFIX_PRERELEASE`.
+		  Empty for not-pre-releases.
+		| `v2.8.2-rc3` `""`
 |`TRUNK`	| GIT: Branch name used for calculation of current codebase
 			  distance from main development.
 			  DEFAULT: empty.
 			| `master`
 |`SUFFIX`	| GIT: Commit count since the tag and hash of the `HEAD` commit
-			  DEFAULT: empty.
+			  DEFAULT: empty for non-prerelease `NUT_VERSION_DEFAULT`
+			  values, or either value of `SUFFIX_PRERELEASE` with a
+			  leading dash for `NUT_VERSION_DEFAULT` values without
+			  git offset info (e.g. `2.8.3.5-rc6` => `-rc6`), or the
+			  whole tail with git and pre-release tag info.
 			| * dev: `-2381+g1faa9945d`
+			  * RC git: `-2381+g1faa9945d+v2.8.3+rc6`
+			  * RC default: `-rc6`
+|`SUFFIX_PRERELEASE`	| GIT: Constructed from `TAG_PRERELEASE` replacing any
+			  dash with a plus character.
+			  DEFAULT: empty unless `NUT_VERSION_DEFAULT` has a
+			  suffix matching the `-(rc|alpha|beta)[0-9]*`
+			  regular expression, or git info followed by
+			  the pre-release tag.
+                          NOTE: No leading dash in this value (unlike `SUFFIX`).
+			| * RC git: `v2.8.3+rc6`
+			  * RC default: `rc6`
 |`BASE`		| GIT: Newest common commit of development `TRUNK` and the `HEAD`
 			  commit (their `git merge-base`).
 			  DEFAULT: empty.
@@ -282,6 +324,11 @@ DESC='v2.8.2-2381+g1faa9945d'
 			  update the `VERSION_DEFAULT` file that goes into "dist"
 			  tarballs; prints its contents
 			| `NUT_VERSION_DEFAULT='2.8.2.2379.2-2381+g1faa9945d'`
+|`UPDATE_FILE_GIT_RELEASE`	| Used in maintainer rituals (requires git) to
+			  update the `VERSION_FORCED` and `VERSION_FORCED_SEMVER`
+			  files that go into "dist" tarballs; prints their contents
+			| `NUT_VERSION_FORCED='2.8.2.2878.3-2881+g45029249f+v2.8.3+rc6'`
+			  `NUT_VERSION_FORCED_SEMVER='2.8.3'`
 |default	| Report `DESC50`	| `v2.8.2-2381-g1faa9945d`
 |=========================================================================
 
@@ -318,6 +365,9 @@ Variables propagated by configure.ac
 |`NUT_SOURCE_GITREV_IS_RELEASE`
 			| Determined by `NUT_VERSION_QUERY=IS_RELEASE gitlog2version.sh`
 			| `true` or `false`
+|`NUT_SOURCE_GITREV_IS_PRERELEASE`
+			| Determined by `NUT_VERSION_QUERY=IS_PRERELEASE gitlog2version.sh`
+			| `true` or `false`
 |`NUT_SOURCE_GITREV_DEVREL`
 			| String determined by `NUT_SOURCE_GITREV_IS_RELEASE`
 			| `"release"` or `"development iteration"`
@@ -345,6 +395,11 @@ Variables propagated by nut_version.h
 		  (falls back to `false` if that query fails)
 		| * `1` if `$GITREV_IS_RELEASE`
 		  * `0` otherwise
+|`#define NUT_VERSION_IS_PRERELEASE <0-or-1>`
+		| Determined by `NUT_VERSION_QUERY=IS_PRERELEASE gitlog2version.sh`
+		  (falls back to `false` if that query fails)
+		| * `1` if `$GITREV_IS_PRERELEASE`
+		  * `0` otherwise
 |=========================================================================
 
 Use in C code

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3457 utf-8
+personal_ws-1.1 en 3458 utf-8
 AAC
 AAS
 ABI
@@ -846,6 +846,7 @@ OUTDIR
 OUTPUTV
 OUTVOLT
 OV
+OVERDURATION
 Oden
 OffTime
 Ohloh
@@ -2686,7 +2687,6 @@ other's
 otheruser
 ouGDQn
 outliers
-OVERDURATION
 ovmf
 pF
 pacman

include/Makefile.am

@@ -36,12 +36,15 @@ MAINTAINERCLEANFILES = Makefile.in .dirstamp
 
 # magic to include Git version information in NUT version string
 # (for builds not made from the tagged commit in a Git workspace)
-
+# NOTE: For pre-releases, SEMVER may differ from NUT_VERSION base
+# (e.g. a commit tagged as 2.8.3-rc5 can have its own NUT_VERSION based
+# on 2.8.2-something, but is assumed as a pre-release for 2.8.3 SEMVER)
 nut_version.h: @FORCE_NUT_VERSION@
 	@echo "  GENERATE-HEADER	$@" ; \
 	 RES=0; \
 	 GITREV="`$(top_srcdir)/tools/gitlog2version.sh`" || GITREV=""; \
 	 GITREV_IS_RELEASE="`NUT_VERSION_QUERY=IS_RELEASE $(top_srcdir)/tools/gitlog2version.sh 2>/dev/null`" || GITREV_IS_RELEASE="false"; \
+	 GITREV_IS_PRERELEASE="`NUT_VERSION_QUERY=IS_PRERELEASE $(top_srcdir)/tools/gitlog2version.sh 2>/dev/null`" || GITREV_IS_PRERELEASE="false"; \
 	 GITREV_SEMVER="`NUT_VERSION_QUERY=SEMVER $(top_srcdir)/tools/gitlog2version.sh 2>/dev/null`" || GITREV_SEMVER=""; \
 	 {  echo '/* Autogenerated file. Do not change. */' ; \
 	    echo '/* This file was generated by "make". */' ; \
@@ -65,8 +68,13 @@ nut_version.h: @FORCE_NUT_VERSION@
 	    else \
 	        echo "#define NUT_VERSION_IS_RELEASE 0" ; \
 	    fi ; \
+	    if $$GITREV_IS_PRERELEASE ; then \
+	        echo "#define NUT_VERSION_IS_PRERELEASE 1" ; \
+	    else \
+	        echo "#define NUT_VERSION_IS_PRERELEASE 0" ; \
+	    fi ; \
 	 } > "$@.tmp.$$$$" && \
-	 echo "NUT_VERSION: \"$$NUT_VERSION\"  NUT_VERSION_IS_RELEASE:$$GITREV_IS_RELEASE  NUT_VERSION_SEMVER: \"$$GITREV_SEMVER\"" && \
+	 echo "NUT_VERSION: \"$$NUT_VERSION\"  NUT_VERSION_IS_RELEASE:$$GITREV_IS_RELEASE  NUT_VERSION_IS_PRERELEASE:$$GITREV_IS_PRERELEASE  NUT_VERSION_SEMVER: \"$$GITREV_SEMVER\"" && \
 	 if test -f "$@" && test -s "$@" ; then \
 		if cmp -s "$@.tmp.$$$$" "$@" ; then \
 			echo "  GENERATE-HEADER	$@ did not change" ; \