Merge ~nicolasbock/git-build-recipe:long into git-build-recipe:master

[Nicolas Bock]

[Colin Watson (cjwatson)]

It's generally a mistake (though a very tempting one) to put git commit IDs in package version numbers, which is what this would do. Git commit IDs aren't ordered in the sense of Debian version comparison. Now, `git describe --tags --abbrev=7` does include the number of commits on top of the latest tag, which mitigates that problem; but the commit ID part is rather unusable.

There's also a non-obvious syntactic problem here. `git describe --tags --abbrev=7` outputs something like "2.11.2-16-gf6fbdf8". But in a Debian version, the "Debian revision" part of the version is defined as the part to the right of the _rightmost_ "-" character (see https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version); that means that a package using such a version would parse as having an upstream version of "2.11.2-16" and a Debian revision of "gf6fbdf8", which is unlikely to be quite correct and which can cause subtle problems.

I recommend instead using some form of the `{revno}` variable (perhaps in addition to `{latest-tag}`) to build up the version of your recipe. This gives you something that fulfils the same purpose as the usable part of `git describe --tags --abbrev=7`, but without the confusing pitfalls. Have you tried that?

review: Needs Information

[Nicolas Bock (nicolasbock)]

Thanks for your comments. I think the main information we are interested in the number of commits after the latest tag. I'll remove the commit SHA.

[Colin Watson (cjwatson)]

Right, but then you can just use the existing `{revno}`. (Admittedly this gives you the number of first-parent commits since the start of the history, not the number of commits since the latest tag; but in my experience that's just as good for including in autogenerated versions, since the important thing is just that each segment of the version is ordered sensibly.)

Unmerged commits

cafac46... by Nicolas Bock on 2023-07-19

Added new variable `{latest-tag-long}`

This variable expands using

  git describe --tags --abbrev=7

To include the number of commits past the latest tag.

Signed-off-by: Nicolas Bock <email address hidden>

diff --git a/gitbuildrecipe/deb_version.py b/gitbuildrecipe/deb_version.py
index f70bc49..b0dc038 100644
--- a/gitbuildrecipe/deb_version.py
+++ b/gitbuildrecipe/deb_version.py
@@ -25,6 +25,7 @@ from gitbuildrecipe.recipe import (
     FormattedError,
     GitCommitVariable,
     LatestTagVariable,
+    LatestTagLongVariable,
     RevdateVariable,
     RevnoVariable,
     RevtimeVariable,
@@ -199,6 +200,9 @@ def substitute_branch_vars(base_branch, child_branch):
     base_branch.deb_version = git_commit_var.replace(base_branch.deb_version)
     latest_tag_var = LatestTagVariable(child_branch)
     base_branch.deb_version = latest_tag_var.replace(base_branch.deb_version)
+    latest_tag_long_var = LatestTagLongVariable(child_branch)
+    base_branch.deb_version = latest_tag_long_var.replace(
+        base_branch.deb_version)
     revdate_var = RevdateVariable(child_branch)
     base_branch.deb_version = revdate_var.replace(base_branch.deb_version)
     revtime_var = RevtimeVariable(child_branch)
diff --git a/gitbuildrecipe/recipe.py b/gitbuildrecipe/recipe.py
index f932ca7..ee29ae5 100644
--- a/gitbuildrecipe/recipe.py
+++ b/gitbuildrecipe/recipe.py
@@ -238,9 +238,24 @@ class LatestTagVariable(RevisionVariable):
             stderr=subprocess.STDOUT).rstrip("\n")
 
 
+class LatestTagLongVariable(RevisionVariable):
+
+    basename = "latest-tag-long"
+
+    minimum_format = 0.4
+
+    def get(self):
+        # Capture stderr so that exceptions are useful.  We know that git
+        # describe does not write to stderr on success.
+        return self.branch.git_output(
+            "describe", "--tags", "--abbrev=7", self.commit,
+            stderr=subprocess.STDOUT).rstrip("\n")
+
+
 branch_vars = [
     GitCommitVariable,
     LatestTagVariable,
+    LatestTagLongVariable,
     RevdateVariable,
     RevtimeVariable,
     ]