Releases and CI

This page says what each workflow of the repository does, how a release is made and what to check before one. The workflows are Forgejo Actions in .forgejo/workflows/, run by Codeberg.

Workflow	Runs when	What it does
ci.yml	A push to main, or a pull request into main	Builds, checks the notices, runs the unit tests and the mail, XMPP, IRC and OpenPGP integration tests
site.yml	A pull request into develop or main, or a push to main, that touches the site	Tests and builds the site, checks pages and links, publishes nothing
version.yml	A push to main, or by hand	Works out the version, writes the changelog, commits and tags
release.yml	A tag v*	Builds the archives and the Debian packages, publishes the release and then the site
nightly.yml	Every night at 03:00 UTC, or by hand	Publishes a build of develop
docs.yml	By hand	Builds the site and publishes it, so a documentation fix does not need a release

The CI

A push to develop or to a feature branch, and a pull request into develop, run nothing: the tests run on my machine there (see Build and test). The CI runs for main, and a change to Markdown, docs/, assets/ or website/ alone does not start it.

It has five jobs in the dotnet/sdk:10.0 image. build-and-unit-tests restores, builds in Release with -warnaserror, checks that THIRD-PARTY-NOTICES.md is up to date and runs the unit tests. The mail, XMPP and IRC jobs run their part of the integration tests against Docker containers, with the network of the host. The OpenPGP job installs gpg, tests scripts/sign-checksums.sh with throw-away keys and runs the OpenPGP tests.

Make a release

A release is the merge of develop into main. I do not edit CHANGELOG.md or the version by hand.

1. Run the unit tests and the integration tests on develop.

2. If the release touches tt, check its pages against the real program, as in the next section.

3. See which version the commits give. It needs git-cliff.

   scripts/prepare-release.sh --dry-run

4. Open a pull request from develop into main, wait for the CI and merge it with a merge commit.

5. Watch Version and then Release on the Actions page. When they are green, the release page has the files, SHA256SUMS and SHA256SUMS.asc.

6. The last job of Release publishes the site. To publish a documentation fix between releases: Actions, docs, Run workflow, with release_tag set to a tag such as v0.5.0, or empty for the branch of the run. With publish off it builds and checks and publishes nothing. The workflow is on the Actions page once it is on main.

7. Pull develop: the release commit is merged back into it.

Check tt and the Reference

The pages about tt are written from the code, and tt changes faster than they do. Before a release that touches tt, I check these against the real program, started with tt --demo:

• Use tt and the Tutorial: every key, command and screen they describe exists, and every checkpoint matches the screen.
• tt commands and contexts and Theme roles: each row is a name the program has.
• tcli commands against tcli --help.

A page is corrected when it is wrong. A Planned aside is removed when the release now has the feature. The screenshots are part of this check: see Screenshots.

How the version is chosen

scripts/prepare-release.sh asks git-cliff for the next version, from the Conventional Commits since the last v* tag. A tag with a dash, such as v0.5.0-rc.1, is not counted.

Commits since the last tag	Release
A feat	Minor
A fix or a perf	Patch
A breaking change: ! after the type, or a BREAKING CHANGE: footer	Minor while Tilde is below 1.0
Only docs, test, chore, refactor and the like	Nothing: the workflow ends green

What the workflows do

Version writes the version in Directory.Build.props (Version, FileVersion and InformationalVersion; AssemblyVersion is the version of the plugin API and stays), regenerates CHANGELOG.md, commits chore(release): vX.Y.Z, tags it and pushes both. It then merges the tag back into develop. If that merge fails, it warns, and I merge main into develop by hand.

Release starts from the tag. It does these steps:

1. Builds tcli and tt as one self-contained file each, for linux-x64, linux-arm64, osx-x64, osx-arm64 and win-x64, one archive per program and platform (scripts/build-binaries.sh).
2. Builds the Debian packages tilde-cli and tilde-tui for amd64 and arm64, and the metapackage tilde-all (packaging/deb/), and tests each of them with packaging/deb/test-deb.sh.
3. Writes SHA256SUMS and signs it with the release key (scripts/sign-checksums.sh).
4. Makes the release as a draft, with the section of the version in CHANGELOG.md as its notes, attaches the files and publishes it.
5. Uploads the packages to the stable distribution of the Debian registry, the metapackage last. A tag with a dash makes a pre-release and skips this step.

To build the files by hand, scripts/build-binaries.sh -p tt -r linux-x64 -o dist makes one archive. --help lists the options.

The nightly

Nightly runs scripts/nightly.sh on develop. The version is the next release plus a marker, like 0.6.0-nightly.202611060300.g1a2b3c4. The packages go to the nightly distribution of the registry, which keeps the last 7, and the archives to one pre-release called nightly, which replaces the one of the night before. A night with no new commit builds nothing. The schedule runs from the copy of the workflow on main. By hand, force builds again a commit that already has its nightly.

Secrets and keys

The repository has three secrets. RELEASE_TOKEN writes the repository and the packages: it pushes the tag, which starts Release, and uploads the files. RELEASE_GPG_KEY and RELEASE_GPG_PASSPHRASE sign SHA256SUMS; without the key the release goes out unsigned. When the key’s expiry is extended, I update both the secret and RELEASE-KEY.asc, because signing with an expired key stops the release. The nightly is not signed. See Check a download.

When a run fails

• Version failed after it pushed the tag: run it again. It finds the tag and goes on.
• Release failed: run it again from the Actions page. A half-filled draft is replaced, and a published release is left alone.
• The pull request of a release failed in the CI: fix it on develop and push.