Releasing

This document will cover how to make new releases of Venator from A-Z. This is only relevant to project maintainers.

Why is Venator versioned?

Versions typically are accompanied by an assumption that the releases are better tested, and overall, generally more stable and less buggy than standard commits to dev. In practice, this is rarely true, especially while Venator is a small project with limited coverage. Instead, Venator aims to make releases as more of a convenience. In the future, versions may receive bug hunt sprints and such, but for now, releases should be provided to provide a common groud for deployments.

If everyone is running slightly different commits from dev, it will be impossible to reasonably aggregate complex bug reports, and administrators will grow tired of updating Venator constantly. In order to prevent some sort of “update fatigue”, releases should be cut often enough that common deployments don’t fall too far behind dev, but not so often that they might as well be individual commits themselves. At the same time, invested users should be encouraged to track the development branch directly, as this is most effective for both discovering new bugs, and also getting them fixed.

Deciding on the next release tag

Venator currently uses zerover for versioning. The first value in the version string must never surpass 0, the second part generally is incremented when new interesting features are added, and the final value is incremented whenever there’s minor changes, such as more minor features, bug fixes, or internal changes.

The second version number should be incremented whenever there are changes (typically new features) that project watchers may be interested in, or if there are fairly major changes since the last release. These should be no more often than once a month, but exceptions can apply.

The final version number should be incremented “whenever” - a good metric is around once a month when there have been several changes since the last release, or when there have been several hundred commits since. This is just to make sure releases don’t fall too far behind development.

Skipping releases

The cycle may be skipped if there are no worth-wile changes since the previous release. For example, if there are only documentation updates, unit test changes, non-security dependency updates, internal refactors, etc, it might be worth just skipping a release. In this scenario, it may be more desirable to wait until some more impactful changes have been made, and then making a release off-cycle (but this should be explicitly communicated).

Compatibility testing

The current state of Venator MUST be backwards compatible with the previous release (excluding pre-releases) at the very least. This can be tested by:

1. Deploying an instance of the previous version.
2. Running some light usage on it (creating multiple accounts, rooms, sending messages, changing profiles, etc).
3. Shutting it down and upgrading the binary without changing any other components.
4. Starting the server again with the new binary and continuing to use it.

If there are any problems with doing this, there SHOULD be a good effort made to restore a seamless upgrade transition. Nobody reads changelogs, don’t lie to yourself.

If it is impossible to seamlessly upgrade, the server should instead attempt to refuse to start if it detects an incompatibility before any data is modified. Nobody backs up their server, or at the very least doesn’t test their backups, don’t lie to yourself. In this case too, it should be made very clear in changelogs that there are breaking changes, and what changes are needed to prepare for the upgrade.

Release checklist

First, do you even need to make a release:

• Has sufficient time passed since the previous release?
• Have notable changes actually been made since the last release? (ideally check at least 2)
  • Has sufficient progress been made in addressing open bug reports?
  • Have any new user-facing features been merged?
  • Have any user-facing optimisations been made
• Will making a new release actually benefit anyone?
• Have any significant changes had enough time to be field tested?

Then, make sure the commit you wish to make a release from is suitable to be a release:

• Does Venator work at the commit you want to make a release from?
  • Does CI pass?
  • Does Venator build and start on both AMD64 and ARM64?
  • Does the Docker image build and start successfully?
• Does the test suite (go test ./...) have a 100% pass rate?
• Have any significant regressions in Complement been addressed? (N/A yet)

If so, you can then start preparing a release:

• Ensure the version in version/version.go has been bumped.
  • Run go test ./version/version_test.go to ensure the version is valid.
• Compile the changelog (N/A until towncrier is set up).
• Build the documentation: mdbook build AND nix run .#generate-nix-docs.
  • If there are any changes, make a new commit describing what changed (can just be chore: Regenerate documentation). Do not bundle them into the release commit.
• Ensure the nix flake hash is correct: nix run .#update-hashes.
  • If there are any changes, make a new commit along the lines of chore: Update nix flake hashes. Do not bundle this into the release commit.
• You can now commit a “chore: Release <version>” commit. Ideally sign it.
• Tag the version against that commit: git tag 0.x.y (without v). Ideally sign it: git tag -S 0.x.y.
• Ensure the version has been incremented as expected: Build Venator with the build script and run venatorctl debug. Check that the version data is as expected. These builds MUST NOT be dirty.
• If any non-metadata changes are necessary, delete the tag, revert the commit, and apply new commits as usual, and try again. If there are metadata changes required, simply amend the commit.
• Push the release commit AND tag.
• Build binaries for the release:
  • Build a static release AMD64 build: GOOS=linux GOARCH=amd64 ./build.sh -release -static. Rename the venatorctl binary to venatorctl-amd64.
  • Build a static release ARM64 build: GOOS=linux GOARCH=arm64 ./build.sh -release -static. Rename the venatorctl binary to venatorctl-arm64.
• Create a release.
  • Name it the same as the tag, this time with the v prefix: v1.2.3 for 1.2.3.
  • Copy and paste the relevant changelog into the tag description.
  • Upload the AMD64 and ARM64 binaries (CI will not do this for you (yet)).
  • Save as a draft and review. The moment you hit publish, people will be notified.

A hop, skip, and a cheer, you’ve just made a new release.

Post-release tasks:

• Make a TWIM post.