refactor: decouple fallback version from Git tags

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -14,7 +14,7 @@ assignees: ""
 - [ ] Locally rendered documentation contains all appropriate pages and other human-written text is up-to-date with any changes in the code.
 - [ ] Installation instructions in the README, documentation, and the website are updated.
 - [ ] Grammar and writing quality are checked (no typos).
-- [ ] `FALLBACK_VERSION` in `site_scons/fallback_version.py` is updated to `<version-number>.post0`. Without this, the SCons build fails after tagging.
+- [ ] Review `FALLBACK_VERSION` in `site_scons/fallback_version.py` for builds without a resolvable release tag.
 - [ ] `scons test` passes locally with the latest conda-forge compilers and dependencies.
 - [ ] Dispatch matrix testing to test the release on all systems. If you do not have permission to run this workflow, tag the maintainer and say `@maintainer, please dispatch matrix testing workflow`. Matrix testing also runs automatically after a GitHub release is published, but it does not block the release, so check that it passes.
 
@@ -23,6 +23,7 @@ Please tag the maintainer (e.g., @username) in the comment here when you are rea
 ### GitHub full-release preparation checklist:
 
 - [ ] The rc GitHub release and its source tarball appear correctly on the releases page.
+- [ ] Build the release source tarball without a Git checkout and verify that its version matches the release tag (with `X.Y.Z-rc.N` normalized to `X.Y.ZrcN`).
 - [ ] Docs are deployed successfully to `https://www.diffpy.org/libdiffpy`.
 - [ ] Successfully run all tests and do functional testing, e.g., with `diffpy.srreal` built against the rc.
 

news/fallback-version.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* Allow updating the fallback version before tagging a release by using it
+  only when no version can be determined from Git or source archive tags.
+
+**Security:**
+
+* <news item>

site_scons/fallback_version.py

@@ -2,10 +2,10 @@
 
 """Definition of FALLBACK_VERSION.
 
-Use it when git repository is not available for example, when building
-from git zip archive.
+Use it when a checkout or source archive has no release tag from which
+to determine the version.
 
-Update FALLBACK_VERSION when tagging a new release.
+Review FALLBACK_VERSION before a release.
 """
 
-FALLBACK_VERSION = "1.4.1.post0"
+FALLBACK_VERSION = "1.5.0rc0.post0"

site_scons/libdiffpybuildutils.py

@@ -15,10 +15,6 @@
     https://github.com/diffpy/libdiffpy/releases
 """
 
-EMSG_BAD_FALLBACK_VERSION = """
-Inconsistent FALLBACK_VERSION {} vs {} from git tag.
-"""
-
 RELEASE_TAG = re.compile(r"([0-9]+\.[0-9]+\.[0-9]+)(?:-rc\.([0-9]+))?")
 
 
@@ -71,18 +67,9 @@ def gitinfo():
 def getversion():
     """Extract version from gitinfo and/or gitarchive.cfg file.
 
-    Process gitinfo first and make sure it matches FALLBACK_VERSION in
-    fallback_version.py.  Use expanded data from gitarchive.cfg when
-    these sources are from git archive bundle.
+    Prefer the version from gitinfo or an expanded git archive tag. Use
+    FALLBACK_VERSION only when neither provides a version.
     """
-    from fallback_version import FALLBACK_VERSION
-
-    if not re.fullmatch(
-        r"[0-9]+\.[0-9]+\.[0-9]+(?:rc[0-9]+)?\.post0", FALLBACK_VERSION
-    ):
-        raise RuntimeError(
-            "FALLBACK_VERSION must be X.Y.Z.post0 or X.Y.ZrcN.post0."
-        )
     gitarchivecfgfile = os.path.join(MYDIR, "gitarchive.cfg")
     assert os.path.isfile(gitarchivecfgfile)
     with open(gitarchivecfgfile) as fp:
@@ -102,12 +89,15 @@ def getversion():
                 gi["patchnumber"] = 0
                 break
     rv.update(gi)
-    if "version" in gi:
-        afb = FALLBACK_VERSION
-        gfb = gi["version"].split(".post")[0] + ".post0"
-        if gfb != afb:
-            raise RuntimeError(EMSG_BAD_FALLBACK_VERSION.format(afb, gfb))
-    else:
+    if "version" not in gi:
+        from fallback_version import FALLBACK_VERSION
+
+        if not re.fullmatch(
+            r"[0-9]+\.[0-9]+\.[0-9]+(?:rc[0-9]+)?\.post0", FALLBACK_VERSION
+        ):
+            raise RuntimeError(
+                "FALLBACK_VERSION must be X.Y.Z.post0 or X.Y.ZrcN.post0."
+            )
         # A development checkout without a new-format tag, or an untagged
         # archive, has no known commit count.  Keep the fallback version.
         rv["version"] = FALLBACK_VERSION