Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 4 committers have signed the CLA.

✅ Evil-Spirit
✅ rhansen
❌ parport0
❌ xythobuz
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

Please don't do this, for several reasons.

1. The 2.x branch is hopelessly obsolete and should never really be touched again. The Snap packages should be described as 3.0~gitXXXXX, not 2.anything.
2. Bugfixes were first applied to master, then to release branch, not the other way around.
3. This will likely cause issues with git bisect.

To be clear, we can take a look at the workflow improvements you're suggesting in the next release branch (if there will be one). But I would strongly prefer to not touch the existing 2.x branch, which is a remnant of an ad-hoc release process that has not been relevant for years.

Sounds good, though there are a couple of things I wanted to point out:

• This doesn't touch the 2.x branch, only master.
• This does not introduce any changes to master (the diff between the merge commit's first parent and the merge commit is empty).

Thanks for the expanded explanation above, I see your rationale more clearly now. Other than for git tag --contains, am I correct that with our workflow and versioning scheme, there would be no practical improvement?

Correct, although it is a prerequisite to switching your snapcraft.yaml to version: git if you wanted to. (Or you could create a tag like v3.0-alpha1 on master.)

A downside of the current snapcraft.yaml versioning scheme is it is non-increasing: 3.0~b55dac76 is newer than 3.0~e51fdf6f but version string comparison tools will believe it is older because the letter b comes before the letter e. On a Debian-based system (e.g., Ubuntu):

$ dpkg --compare-versions 3.0~b55dac76 gt 3.0~e51fdf6f && echo true || echo false
false

Using git describe to generate the version string avoids this problem via a "number of commits since the tag" part (the 687 in v2.3-687-g888ed334 means the 888ed334 commit is 687 commits past the v2.3 tag).

I don't think that Snapcraft version strings are subject to the same semantics as Debian package version strings, but it's probably good practice to follow something like the Debian version string semantics.

I understand your motivation for using version: git now. In principle, that makes sense. However, for Snaps, Snapcraft enforces a monotonically increasing revision order, so it is not an issue. For Debian packages, my understanding is that the packager would also use a monotonically increasing revision order that is specific for that particular package, so it is not an issue there either. (For a while I maintained a Debian package upstream, but then a Debian maintainer came and in fairly strong terms asked me to stop. Since that package and its nightly builds were a constant headache anyway I was happy to oblige.)

For context, the ~e51fdf6f part of the version string was never supposed to be compared. I added it a long time ago to the About dialog to make bug reports more useful. I think that was before I was aware of workflows using git describe. In semantic terms, all 3.0~ versions are pre-releases of 3.0 and have no particular ordering.

I have two concerns about switching to git describe.

1. Unlike the current scheme, using it would break shallow checkouts, which are handy for CI servers and such.
2. The "number of commits since the tag" part works well if you publish (pre-release) packages with this versioning scheme to a centralized package registry. In that case, you can maintain a single chain of commits in the way you proposed in this PR, and the number of commits since the tag is well-defined. But with something like SolveSpace, the purpose of the git hash in the version string is to clearly identify experimental builds, builds from various branches, third-party builds, etc, none of which are ordered with regards to the mainline development.

It seems to me like the disadvantages of using git describe outweigh the advantages. Perhaps we should more clearly emphasize that git hashes should not be compared? If I recall correctly, PyPI uses versions like 3.0.g<HASH> rather than 3.0.<HASH> to avoid this kind of problem--perhaps we should do that instead?

You are right that git describe doesn't work in a shallow clone—it requires cloning enough commit history to get the most topologically recent tag.

I looked into Snapcraft's version string a bit more and it looks like it's meant for human consumption, not machine consumption (unlike Debian package version strings). So the current version scheme is perfectly fine for Snap.

Perhaps we should more clearly emphasize that git hashes should not be compared?

I don't think that's necessary. Humans understand that hashes aren't ordered, and any package maintainer will know to munge the version string to avoid hash comparisons.

Speaking of munging version strings, how much do you care about consistency between Help->About and package versions? Right now a Debian package maintainer would need to generate a version string via git describe or a date-based scheme (e.g., 3.0~20200421.0-g45eb2468) in order to package up a pre-release version of SolveSpace. Because of this, the package version would not match Help->About.

If I recall correctly, PyPI uses versions like 3.0.g<HASH> rather than 3.0.<HASH> to avoid this kind of problem—perhaps we should do that instead?

That doesn't solve the Debian comparison problem—it would still try to compare ge51fdf6f with gb55dac76 and get the wrong answer. Adding a g prefix does have a few other advantages:

• For humans, the g acts as a hint for humans that the following hash is an abbreviated Git commit ID.
• For machine parsing:
  • The g makes it easier to write code that reliably extracts the commit ID from the version string.
  • The g helps avoid parsing ambiguity in case the hash looks like something else.
  • The g makes it easier to update tooling when switching from Git to some other version control system that also uses hashes to identify commits.

But with something like SolveSpace, the purpose of the git hash in the version string is to clearly identify experimental builds, builds from various branches, third-party builds, etc, none of which are ordered with regards to the mainline development.

Note that the output of git describe includes the abbreviated commit ID to disambiguate all of the commits that are exactly N away from the tag. For example, v2.3-687-g888ed334 refers to the commit with hash 888ed334.

Also, context matters. If the version string came from Snap or a Linux distribution then it would be clear what the string referred to. If the version string came from someone building their own personal branch then it wouldn't have much meaning, but that's also true with the current version scheme.

You are right that git describe doesn't work in a shallow clone—it requires cloning enough commit history to get the most topologically recent tag.

Another thing it doesn't work well with is git archive. (You already can't build SolveSpace from tarballs generated by it--for some incomprehensible reason this command is not able to package submodules--but I have some hope that one day it'll be fixed, and GitHub's tarball downloads would become useful.)

Because of this, the package version would not match Help->About.

That's not an issue. All I want is to be able to look up the hash to conclusively identify which commit in the repository it was built from (or a lack of such commit). If the About dialog text clearly identifies the build as coming from Debian (or at least, modified by a packager), that is all the better.

Also, context matters. If the version string came from Snap or a Linux distribution then it would be clear what the string referred to. If the version string came from someone building their own personal branch then it wouldn't have much meaning, but that's also true with the current version scheme.

Yes. Let me rephrase my earlier statement. I think that not having a "number of commits since tag" part at all is better than having one that would be sometimes missing (because of shallow checkouts), sometimes misleading (because of third party builds), and sometimes correct; there's nothing more frustrating than apparently helpful but in reality misleading metadata. If I have to disambiguate it with the commit hash to be sure, why bother having it at all?