Releasing

Releasing

A release is a version tag on a commit of the root branch. Pushing the tag makes the Release workflow (.github/workflows/release.yml) build that commit from scratch for every platform and publish a GitHub release with the binaries. Like the daily to yearly builds below, nothing is restored from or saved to a cache, so the binaries are clean. The build takes as long as a Periodic run.

Cutting a release

1. Tag the commit and push the tag:

   git tag 0.2.0 <commit>
   git push origin 0.2.0

2. Watch the Release workflow. It creates the release with the tag as its title.

Tag names are numbers only, with no v: 0.2.0, or 0.2.0.1. A suffix after a dash such as 0.2.0-rc1 makes it a pre-release. The nightly, daily, weekly, monthly and yearly tags never match, so they are unaffected. They stay on their own blank commits, and the release workflow never touches them.

To build and release a tag that exists already (a failed run, or to replace the binaries), start the workflow by hand: Actions > Release > Run workflow, with the tag in the tag field. The workflow never creates tags, and refuses names that are not release tags.

What is published

• The assets are the packages of the clean build, named like the nightly release: blitzllvm-<version>-<commit>-windows-x64.zip for Windows, and the packages .deb, .rpm, .pkg.tar.zst, .snap (Linux) and .pkg (macOS). Linux has no zip. The <version> in the file names is the timestamp version of the tagged commit (see cmake/project_version.cmake), not the tag name, and <commit> is its 7 character hash.
• The description lists the commit subjects since the previous release tag, grouped into Added, Fixed, Documentation and Changed by the first word of the subject, and ends with a compare link. Merge commits, bot commits and Update copyright headers are left out. Write commit subjects accordingly.
• The previous release tag is the highest lower version tag, ignoring nightly. A stable release compares against the last stable release, a pre-release against the last tag of any kind. The first release lists the whole history.

Failures

• A platform fails to build: the whole run fails and nothing is published. Fix the cause on root, move or recreate the tag, and run the workflow again.
• The release is only created after every platform built. Re-running the workflow for an existing release replaces its assets and description.

Trying the release notes

The script can be run locally in a clone with all tags and history. --dry-run prints the notes and the plan, and does not talk to GitHub. The tag does not have to exist yet, HEAD then stands in for it:

.github/scripts/release.py 0.2.0 --dry-run

Daily, weekly, monthly and yearly builds

The Periodic workflow (.github/workflows/periodic.yml, script .github/scripts/periodic.py) runs every day at 05:00 UTC and builds four pre-releases: daily, weekly, monthly and yearly. They are for people who want a build that changes less often than the nightly one. They are not copies of the nightly build. Each build starts from a fresh checkout of the latest root commit and compiles everything, with no cache restored or saved (no dependency cache, no package cache), so the binaries are clean and a stale cache can never end up in them. It is the full Nightly pipeline (nightly.yml, called with clean: true) for every platform, architecture and package.

• A release is built when it does not hold the latest commit yet, and its last build was in an earlier day, ISO week (starting Monday), month or year. So daily takes the latest commit of each day, weekly the first one of each week, monthly the first of each month and yearly the first of each year. A run that GitHub skipped is made up by the next one. When nothing is due, no build starts. When several are due on the same day, they share one clean build.
• The new files are uploaded first, the old ones deleted afterwards, and the description is written last, so a failed run is simply repeated by the next one. The description carries the commit and the time of the build, which the next run reads back.
• The first time, the tag is created on a blank commit without files, as for nightly. Tags are never moved or force pushed.
• The workflow needs contents: write. For pull requests it only runs when the workflow or its script change: it then builds everything clean but publishes nothing.
• The nightly build keeps its caches. Only the Periodic builds are clean, so expect them to take much longer (see the run times of the Periodic workflow).

To try it, start the Periodic workflow by hand (Actions, Periodic, Run workflow). It is a dry run by default and prints what is due. Untick dry_run to build and publish right away, and use force to ignore the checks above. Locally, with the GitHub CLI signed in, .github/scripts/periodic.py plan --sha <commit> prints what is due, and --now 2026-11-01T05:00:00Z shows what a run at another time would do.