Improved versioning

[matthijskooijman]

This implements the improvements suggested at #608 (comment). Practically, this PR makes the following improvements:

• The version number for releases is now in a single file called src/hamster/VERSION instead of being hardcoded in multiple places.
• The git version determination is also no longer duplicated in two places.
• The fallback version for unreleased versions is now unreleased instead of 3.0.2 (i.e. when running from a source checkout or tarball that is not from a released version, and git cannot be used to determine the version, this no longer incorrectly shows 3.0.2).
• The version number detected from git now has the v prefix stripped, making version numbers consistent between git checkouts and release tarballs.
• The flatpak build now knows about the version number it contains.
• The flatpak build now can actually use the metainfo.xml file.

I'm marking this as a draft since I still need to do a bit more testing, and because I found out just before I ran out of time for today, that flatpak seems to insist on having a release date with the version number in metainfo.xml and otherwise just ignores the version number entirely (F: Ignoring release element without timestamp or date). To solve this, we should either:

1. Autodetect the release date (meaning take it from the git tag or commit date if available, and, I guess, add a RELEASE_DATE next to VERSION for release tarballs).
2. Just add a fake date (something like a zero timestamp or date far into the past that is clearly not meaningful)

I've implemented 2. for now, but comments are welcome.

[github-actions]

Automatically generated build artifacts for commit 3d161a8 (note: these links will expire after some time):

• Flatpak application: ⏬ Download

---

To test this PR, download and unzip the flatpak application above and then install with:

flatpak install Hamster.flatpak

[GeraldJansen]

Looking good. My only suggestion for a fallback version is that "3.0.2-derived" or some such notation would be more informative than "unreleased". After the 3.0.3 release the VERSION file would be updated to ""3.0.3-derived". However, this is of marginal importance so feel free to drive on!

[matthijskooijman]

Looking good. My only suggestion for a fallback version is that "3.0.2-derived" or some such notation would be more informative than "unreleased". After the 3.0.3 release the VERSION file would be updated to ""3.0.3-derived". However, this is of marginal importance so feel free to drive on!

Right, that would make some sense, but be slightly harder to maintain (but might be good to do if we automate that later). In practice, it should not matter much, since the unreleased should hardly ever be used, since during normal development git version will be used anyway.

Here's a bit of documentation (that I wanted to write anyway) about how the versioning now works (to be put somewhere):

For determining the hamster version, there are currently two interfaces:

• The hamster.__version__ variable is to be used from within hamster itself, to figure out the version of the code that is currently running. This works both when installed or running out of a source tree (git checkout or unpacked tarball). When not installed, this version includes an "(uninstalled)" suffix.
• The src/hamster/version.py script can be run by itself to get the version of the source tree, to be used by e.g. waf or later github actions to get the source tree version (does not work when installed). This does not return the "(uninstalled)" suffix.

To find the actual version number, three options are tried in order:

1. The hamster/defs.py file. This file is not present in the source tree, but generated by waf during install. This is only considered for hamster.__version__, not for the src/hamster/version.py script.
2. The git version. This runs git describe with some options to figure out the most recent tag, any commits made on top of this, and if the source tree is modified. For example, 3.0.2-75-ga0fe41d0+ indicates that the most recent tag is 3.0.2, 75 commits have been made since then, the most recent commit is a0fe41d and the source tree was modified. When the current version is an unmodified tag, this returns just the version number.
3. The contents of src/hamster/VERSION. This is used for source trees without git information (typically when installing from a tarball git export for releases). This file only has meaningful content in git for release commits, and is reverted to a plain unreleased value directly after the release (but during development the git version should usually be used).

[GeraldJansen]

documentation ... (to be put somewhere)

Created wiki page Versioning, for now.

[aquaherd]

There is a .bumpversion and setup.py in the root. You may want to review or drop them in this endeavour.

[github-actions]

Automatically generated build artifacts for commit 7f9bdb3 (note: these links will expire after some time):

• Flatpak application: ⏬ Download

---

To test this PR, download and unzip the flatpak application above and then install with:

flatpak install Hamster.flatpak

[github-actions]

Automatically generated build artifacts for commit c01b74c (note: these links will expire after some time):

• Flatpak application: ⏬ Download

---

To test this PR, download and unzip the flatpak application above and then install with:

flatpak install Hamster.flatpak

[github-actions]

Automatically generated build artifacts for commit 4bf6e78 (note: these links will expire after some time):

• Flatpak application: ⏬ Download

---

To test this PR, download and unzip the flatpak application above and then install with:

flatpak install Hamster.flatpak

[matthijskooijman]

There is a .bumpversion and setup.py in the root. You may want to review or drop them in this endeavour.

Good point, I've removed them. I've also pushed a few other commits and did some more testing, I think this is now ready for final review. @aquaherd, @DirkHoffmann, maybe you could have another review pass over the new commits?

If ok, let me handle the merge, there is still a fixup commit to be squashed before merging.

[aquaherd]

date should be an easter egg: "2007-08-01" Toms first commit to the repo

[matthijskooijman]

I'm afraid that such a date might actually look like its meaningful, 1980-01-01 is even more clearly invalid/fake. I'm not entirely sure where this date will actually show up, though, but I'm inclined to leave it as is?

[aquaherd]

I have built a tar release with ./waf dist but the magical substitution from defs.py.in to defs.py did not happen. Does the release pipeline handle this?

AFAIK, downstream packagers prefer to download the tar.gz file and do not do a git checkout from github just to get a version string.

[matthijskooijman]

I have built a tar release with ./waf dist but the magical substitution from defs.py.in to defs.py did not happen. Does the release pipeline handle this?

Right, I did not look at that case yet. I think it should (be made to) include the src/hamster/VERSION file, and then everything would be ok. Let me check that.

AFAIK, downstream packagers prefer to download the tar.gz file and do not do a git checkout from github just to get a version string.

For at least Debian, I think that is the case, though the previous release did not have a tarball from us, so I'm assuming @rhertzog has used a git export or something like that.

Also, the approach with adding a VERSION file manually in git (as opposed to auto-generating a tarball with a github workflow or so), has the advantage that you can just export a tarball from git and have that work (and is, at least for now, simpler so a better way to move forward).

The question is, though, should we (as part of the release process) generate such a tarball (either directly from git, or using ./waf dist) and publish it as part of the github release maybe?

[matthijskooijman]

I just tried ./waf dist, which seems to basically just tar up the current directory (including any temporary and .gitignored files lying around), so it seems to be easy to create bundles with too much files in them. But src/hamster/VERSION is also included, so it seems things should work fine for release builds (i.e. when src/hamster/VERSION contains a meaningful version, for a dist created from a random git commit, you get "unreleased" as the version number, but I'm not sure if that's a case that we need to better support, probably not?).

[aquaherd]

The problem is the packagers: They only monitor the most recent tag, add that to a github URL and then unpack the github generated tar file, dropping the first folder level that is the only thing that contains a string like v3.0.3.

Previously, the 3.0.2 was inside the sources. I have not yet seen a release build so I ight be wrong. I don't see any modification on how the release tar is built here, so I assume it is just a tar from a git tag, that does not include the tag name in the tar file.

[matthijskooijman]

Previously, the 3.0.2 was inside the sources. I have not yet seen a release build so I ight be wrong. I don't see any modification on how the release tar is built here, so I assume it is just a tar from a git tag, that does not include the tag name in the tar file.

The plan is to write 3.0.3 to src/hamster/VERSION in a commit, tag that, and then revert to unreleased in a subsequent commit, exactly so the workflow you describe should work. See also #686 (comment)

[DirkHoffmann]

Not sure, if it is relevant for this issue, and if it is to be fixed on your side or on my test system, but I get these two messages from flatpak when installing Hamster-3.0.2-81-g14262.flatpak:

Info: runtime org.gnome.Platform branch 41 is end-of-life, with reason:
   The GNOME 41 runtime is no longer supported as of September 17, 2022. Please ask your application developer to migrate to a supported platform.
Info: applications using this runtime:
   org.gnome.Hamster

Info: runtime org.freedesktop.Platform.GL.default branch 21.08 is end-of-life, with reason:
   org.freedesktop.Platform 21.08 is no longer receiving fixes and security updates. Please update to a supported runtime version.
Info: applications using this runtime:
   org.gnome.Hamster

[DirkHoffmann]

Looking good. My only suggestion for a fallback version is that "3.0.2-derived" or some such notation would be more informative than "unreleased".

Shouldn't it be "rcN" (with N=1, 2, …)?

[matthijskooijman]

The GNOME 41 runtime is no longer supported as of September 17, 2022. Please ask your application developer to migrate to a supported platform.

This I fixed today in #739, but this PR is not rebased on top of that yet.

Shouldn't it be "rcN" (with N=1, 2, …)?

That would make sense for explicit release candidate images, but @GeraldJansen is talking about the fallback VERSION file contents, that gets used when an unreleased source tree is used in a context where no git information is available.

[matthijskooijman]

I think all concerns have been answered. In the interest of progress, I'm going to go ahead and merge this already, so we can prepare for the last steps of the release. If there's anything that still needs to be changed or discussed, before or after the release, feel free to leave more comments.