Document & improve release process

[matthijskooijman]

I'm currently working on the 3.0.2 release.

The full release process should be documented somewhere. For now, I'll use this issue to keep notes, this should probably move into the repo somewhere (CONTRIBUTING.md? Or a separate file? In a subdir to keep things clean? Or the wiki?).

I'm basing on #588 (comment) and https://github.com/projecthamster/hamster/projects/1#card-27399663.

Here's the steps I am going through:

• Update NEWS file. This is done manually, see Automate NEWS generation #607 for some thoughts on automating this. I've only added changes here that affect release users (e.g. visible changes in hamster, but also in the build process, but not the addition of automated tests in github). Where a change has a related PR and issue, I've referenced the issue (since that is typically the issue fixed, and points to the PR anyway. This also seemed existing practice).
• Bump the version number. In the project card, ederag noted "update version number manually (bumpversion is a time drain)". I wondered a bit about that, since there is a .bumpversion.cfg file in the repo. I tried bumpversion (and also bump2version a more up-to-date fork) which indeed behaved a bit surprising. It might be useful, but for now I just updated the version manually in src/hamster/__init__.py, wscript and .bumpversion.cfg (based on the bumpversion config and earlier bump commits).
  For the future, maybe we can put the version number just in one place somehow? Maybe even not put the version number in git (so always detect the git version when installing from git), and write the version number (based on the git tag) into the source tarball at release time (automated using a script, maybe even run from a github action).
• There is probably something that needs to happen with translations. The project card has some related points, but these are outdated according to ederag. Since the 3.0.2 release is not touching any translated strings, I'm just going to leave this for now, but we have to figure this out later.
• In the project card, a number of steps related to creating the release description are mentioned. In particular, this talks about adding links to the full list of commits, and links to the contributors pages on github (e.g. see https://github.com/projecthamster/hamster/releases/tag/v3.0). I'm not so sure if I want to keep adding those, since people can easily reach the same information using the github interface. Also, I think it would be good if the release description can be prepared beforehand. So we can make a release-PR and once it is merged, just copy the release description out of the PR description or maybe the NEWS file. I tend towards the latter, adding a small release summary above the list of fixed issues in the NEWS file, and maybe also including the list of fixed issues in the release description? Alternatively, we could prepare a draft release in github (along with the release PR), and finalize that to let github create the tag after merging the PR.

I'm out of time for now, but I'll create a PR with the NEWS and version changes soon. Once that is reviewed and merged, a tag and release must be created, which probably be done at the same time through github.

[mwilck]

I'd done some work on translations in #559.

[matthijskooijman]

Release PR created, and draft release prepared. I ended up writing the release message only on github, not in the NEWS file, but I did include the full changelist from NEWS in the release message.

I noticed one inconsistency in the current release strategy: If you build from a git tag, the version will be set to e.g. v3.0.2, but if you build the same version from a tarball, the version is 3.0.2. This is not really problematic, but I'd prefer straightening this out in the future.

[matthijskooijman]

We might want to consider creating annotated tags, rather than lightweight tags, for releases. These have some extra information (e.g. we could add the release notes in them), but also store a date and author, for a bit more traceability, and can optionally be gpg-signed (which is probably a good idea). Also, the Debian packaging tool I use (git-buildpackage) only considers annotated tags.

[mwilck]

We do already signed commits. AFAIK a "signed tag" implies that it is annotated, too.

[matthijskooijman]

We do already signed commits.

Do we? Not for this repo, I think?

AFAIK a "signed tag" implies that it is annotated, too.

Yes, but none of the tags are currently signed AFAICS?

[mwilck]

I thought we did. But I confused that with the GNOME extension repo I guess. Sorry.

IIRC we have not made it a strict policy. @elbenfreund had originally suggested it in the "heap of gratitude" thread but then reverted because there'd been some resistance to the idea to have to sign every commit. I, too, would prefer to have to sign merges and tags (and perhaps the topmost commit of PRs) only.

[matthijskooijman]

I had another look at the version number stuff, and (ignoring bumpversion) there are two places that currently list a version number:

• src/hamster/__init__.py defines a __version__ variable (which is used by other code), which takes its value from defs.py if installed, otherwise from git describe, falling back to a hardcoded version.
• During install the waflib takes the version from git describe, falling back to a hardcoded version. This version number is then put into defs.py to be used in the installed version.

This means that in both cases, the hardcoded version number is only used as a fallback - if running from a git checkout, it is never used, only when running from a tarball.

So, I suggest we remove these version from git master altogether - when running a development version, the git describe version should always be used and if that is not available (e.g. when downloading a tarball or zip from github) falling back to 3.0.2 for such a case is not actually correct - I'd rather use a clearly invalid version (something like 0.0.0, or "development") than something that looks like it is in unmodified 3.0.2 but actually isn't.

The only case where a hardcoded version makes sense is the release tarball.

I also think that putting the version number in 1 place instead of 2 would be preferred, so maybe just a plain file called VERSION or so that is read from both places. That file can then be present in the release tarball and omitted in git master during development.

For the release tarballs, I can see two routes:

1. Commit a hardcoded version number in git for the release, tag it, and then remove the version number again directly in the git master branch. This allows using github's builtin download and/or export features to generate release tarballs that can be used, but creates some extra noise in the git history.
2. When doing a release generate release tarballs that contain files from git, but modified to add the version number. Thes tar

Option 1 is what has been done in the past (except the version was never removed, so was kept in git master until the next release).

I'm not quite sure which of these options is better. I like option 2, because it eliminates noise, duplication and manual work. The only place in the workflow where a version is put is in the git tag (though in practice also in the changelog/NEWS file), and everything is generated from that. The downside is that the release tarball must be generated and is not identical to the git repo contents for the tag, which is inelegant (but also quite common for projects, I think).

@DirkHoffmann @mwilck @GeraldJansen @rhertzog, Any opinions or suggestions?

[GeraldJansen]

@matthijskooijman You have clearly analyzed this thoroughly. I suggest a VERSION file (for use as fallback only) always be included in the repo. It would normally contain "hamster-master" and for the short time of releasing it would contain the value of the release tag. However, I'm happy with whatever solution you land on.