ci(release): publish releases from a tag, not from a laptop

There was no release workflow. Artifacts were built by `x release --publish` on
whatever machine the maintainer was sitting at, from whatever happened to be in
bin/, with no checksums and nothing proving the tagged tree passed its tests.

Pushing a v* tag now publishes. The workflow builds the toolchain from the IR
seed, runs `x test`, `x test-tools` and `x bootstrap-cfree` against the tagged
tree, and only then creates the Forgejo release. It refuses to publish when the
tag and VERSION disagree, or when CHANGELOG.md has no section for that version.

`x publish [vX.Y.Z]` is the command behind it and runs locally too. It builds
dist/ — a source tarball from the tag, this host's toolchain, and a SHA256SUMS
covering both — and takes the release notes from that version's CHANGELOG
section, so notes and changelog cannot drift. It only adds assets the release
is missing, which is how a macOS build gets attached to a Linux-built release.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.forgejo/workflows/release.yml

@@ -0,0 +1,99 @@
+name: release
+
+# Cutting a release is `x release` + `git push --tags`; everything after that
+# happens here. Before this workflow existed the artifacts were built on whatever
+# machine the maintainer happened to be sitting at, from whatever was in bin/ at
+# the time, with no checksums and nothing proving the tagged tree even passed its
+# tests. Now the tag is the trigger and CI is the only thing that publishes.
+#
+# The job refuses to publish unless:
+#   * the tag matches the VERSION file in the tagged tree,
+#   * CHANGELOG.md has a section for that version (it becomes the release notes),
+#   * the toolchain builds from the IR seed and the whole suite passes,
+#   * the C-free bootstrap still reproduces the seed byte-for-byte.
+#
+# Needs a repository secret FORGEJO_TOKEN with write access to releases.
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to publish (e.g. v0.4.0)'
+        required: true
+
+jobs:
+  publish:
+    runs-on: docker
+    container: node:20-bookworm
+    steps:
+      - name: Install clang-16
+        run: |
+          set -eu
+          export DEBIAN_FRONTEND=noninteractive
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends clang-16 git ca-certificates curl
+          clang-16 --version | head -1
+
+      - name: Check out the tag
+        env:
+          REPO_URL: ${{ github.server_url }}/${{ github.repository }}.git
+          INPUT_TAG: ${{ github.event.inputs.tag }}
+        run: |
+          set -eu
+          git config --global --add safe.directory '*'
+          # A full clone: `git archive` needs the tag object, and the tarball is
+          # built from the tag rather than from the working tree.
+          git clone "$REPO_URL" .
+          TAG="${INPUT_TAG:-${GITHUB_REF_NAME}}"
+          git checkout "$TAG"
+          echo "TAG=$TAG" >> "$GITHUB_ENV"
+          # See ci.yml for why the Linux build injects the stdio shim via LUDIC_CC.
+          echo "LUDIC_CC=clang-16 $(pwd)/tools/ci/linux_stdio_shim.ll" >> "$GITHUB_ENV"
+          echo "LUDIC_HOME=$(pwd)" >> "$GITHUB_ENV"
+
+      - name: The tag, VERSION and CHANGELOG must agree
+        run: |
+          set -eu
+          VERSION="$(cat VERSION)"
+          if [ "$TAG" != "v${VERSION}" ]; then
+            echo "::error::tag ${TAG} does not match VERSION (${VERSION})"
+            exit 1
+          fi
+          if ! grep -q "^## v${VERSION} " CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## v${VERSION}' section to use as release notes"
+            exit 1
+          fi
+          echo "publishing ${TAG}"
+
+      - name: Build the toolchain from the IR seed (clang only)
+        run: |
+          set -eu
+          mkdir -p bin
+          clang-16 tools/ci/linux_stdio_shim.ll selfhost/ludicc.seed.ll -o bin/ludicc
+          bin/ludicc tools/x/main.ludic -o bin/x
+          bin/x build
+
+      - name: The tagged tree must pass its own suites
+        run: |
+          set -eu
+          bin/x test
+          bin/x test-tools
+          bin/x bootstrap-cfree
+
+      - name: Publish the release
+        env:
+          FORGEJO_TOKEN: ${{ secrets.FORGEJO_TOKEN }}
+          LUDIC_FORGEJO_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+        run: |
+          set -eu
+          if [ -z "${FORGEJO_TOKEN:-}" ]; then
+            echo "::error::No FORGEJO_TOKEN secret; cannot create the release."
+            exit 1
+          fi
+          # x publish builds dist/ (source tarball from the tag, this host's
+          # toolchain, SHA256SUMS), takes the notes from the CHANGELOG section,
+          # and creates the release. Re-running it only adds missing assets, so
+          # a maintainer can afterwards attach the macOS toolchain from a Mac
+          # with the same command.
+          bin/x publish "$TAG"

CONTRIBUTING.md

@@ -18,7 +18,7 @@ runtime, and the tooling are all written in Ludic and built by Ludic.
 From a clean checkout, one line lifts the toolchain off the seed:
 
 ```bash
-clang selfhost/ludicc.seed.ll -o bin/ludicc && bin/ludicc tools/x/main.ludic -o bin/x
+mkdir -p bin && clang selfhost/ludicc.seed.ll -o bin/ludicc && bin/ludicc tools/x/main.ludic -o bin/x
 ```
 
 That gives you `bin/x`, the Ludic task runner that replaces every build/test
@@ -73,17 +73,39 @@ The toolchain is versioned with [SemVer](https://semver.org); `VERSION` is the
 single source of truth and `ludicc --version` (or `x version`) reports it.
 
 Releases are changeset-driven. Every user-facing change ships with a changeset
-(step 5 above). To cut a release:
+(step 5 above). Read the next release before cutting it:
+
+```bash
+x release --dry-run             # render the CHANGELOG section, write nothing
+```
+
+Then cut it:
 
 ```bash
 x release [major|minor|patch]   # omit the level to derive it from the changesets
+git push origin main --follow-tags
 ```
 
-That aggregates the pending changesets into a new `CHANGELOG.md` section, bumps
+`x release` aggregates the pending changesets into a new `CHANGELOG.md` section
-`VERSION`, commits `chore(release): vX.Y.Z`, and tags it. Add `--publish` (with
+— grouped by change type, with each changeset's markdown kept intact — bumps
-`FORGEJO_TOKEN` set) to also push and create the Forgejo release with source and
+`VERSION`, commits `chore(release): vX.Y.Z`, and tags it.
-toolchain tarballs. The tag doubles as the reproducible bootstrap point: the
+
-source archive plus its checked-in seed rebuild that exact toolchain.
+**Pushing the tag is what publishes.** The `release` workflow builds the
+toolchain from the IR seed, runs `x test`, `x test-tools` and `x bootstrap-cfree`
+against the tagged tree, and only then creates the Forgejo release — with the
+source tarball, a Linux toolchain build, `SHA256SUMS`, and that version's
+`CHANGELOG.md` section as the notes. It refuses to publish if the tag and
+`VERSION` disagree or the changelog has no section for it.
+
+macOS artifacts cannot be produced on the Linux runner. To attach one, run the
+same command CI runs from a Mac — it only adds assets the release is missing:
+
+```bash
+FORGEJO_TOKEN=… x publish v0.4.0
+```
+
+The tag doubles as the reproducible bootstrap point: the source archive plus its
+checked-in seed rebuild that exact toolchain.
 
 ## Conventions
 

changes/release-ci.md

@@ -0,0 +1,14 @@
+bump: minor
+type: ci
+Releases are published by CI from a tag instead of by hand from a laptop. The
+new `release` workflow triggers on a `v*` tag, builds the toolchain from the IR
+seed, runs `x test`, `x test-tools` and `x bootstrap-cfree` against the tagged
+tree, and only then creates the Forgejo release. It refuses to publish when the
+tag and `VERSION` disagree or `CHANGELOG.md` has no section for that version.
+
+`x publish [vX.Y.Z]` is the command behind it and works locally too: it builds
+`dist/` (a source tarball from the tag, this host's toolchain, and a
+`SHA256SUMS` covering both — releases previously shipped no checksums) and takes
+the release notes from that version's `CHANGELOG.md` section, so the notes and
+the changelog cannot drift. Re-running it only adds assets the release is
+missing, which is how a macOS build gets attached to a Linux-built release.