Releasing Digital Rust #
A release is one annotated tag push and one upload. The Spindle pipeline in
.tangled/workflows/release.yml is a gate: it checks that the tag is annotated,
that the version agrees everywhere, and that the release files build. It
publishes nothing.
Publishing is a browser upload on the tag page. A Tangled release artifact is an
org.tangled.repo.artifact record in the repository's own account on its knot,
and that record is written through an atproto OAuth flow, so a pipeline cannot
create it. The tag page at tangled.org/katsuricata.com/DigitalRust renders the
download list from those records.
The pipeline has no build step. The deliverables are the files in static/ports/
and the two specifications, so a release packages what the tag already holds. This
keeps the run well inside the five minute microvm timeout, and it means a release
does not depend on the network.
What a release ships #
| File | Contents |
|---|---|
digital-rust-ports-vX.Y.Z.zip |
Every file in static/ports/, one port per tool |
digital-rust-agentskill-vX.Y.Z.zip |
The agent skill, ready to install |
digital-rust-syntax-highlighting-specification.md |
The canonical syntax and palette spec |
digital-rust-ui-specification.md |
The canonical UI specification |
SHA256SUMS.txt |
Checksums for the files above |
scripts/make-archives.py builds these into .release/dist, and it refuses to
build when the version on the tag, the version in the syntax specification's
version history, and the version in package.json disagree. The site's version
badge reads the specification, so a mismatch would ship a release that reports
another number.
It also refuses a theme manifest that Firefox would reject: one with no version
AMO accepts, no theme.colors, or a gecko id that another manifest already claims.
A theme version belongs to the add-on rather than to the specification, so that
number is not compared with the tag.
Cutting a release #
Run the local checks and confirm the archives build:
pnpm install
pnpm check && pnpm lint && pnpm contrast
pnpm build
python3 scripts/make-archives.py --version 1.3.1 --check-only
git tag -a v1.3.1 -m "Digital Rust v1.3.1: Safe Mode in the agent skill"
git push origin v1.3.1
Watch the gate on the tag:
tg pipeline list katsuricata.com/DigitalRust
tg pipeline logs <id>
When it passes, build the files you will upload:
python3 scripts/make-archives.py --version 1.3.1
ls -la .release/dist
Open https://tangled.org/katsuricata.com/DigitalRust/tags/v1.3.1 while signed
in as the owner. The artifact control sits on the tag page. Upload every file in
.release/dist. Each file can be at most 50 MB.
Then check that the release is actually downloadable:
curl -sIL "https://tangled.org/katsuricata.com/DigitalRust/tags/v1.3.1/download/digital-rust-ports-v1.3.1.zip" | head -1
A 302 that resolves to 200 means the artifact is attached. A 404 means the
tag page has no record for that file name.
When the upload fails #
An empty XRPCError banner, or a tag page with no artifact list after an upload,
usually means the browser session predates Tangled 1.0. The artifact write needs
the repo:org.tangled.repo.artifact scope, which older sessions do not hold. Sign
out of Tangled and sign in again, then retry the upload. If it still fails, open
the browser's network panel and read the response body of the failing POST to the
knot. That body names the real error.
Rules the pipeline depends on #
- The tag must be annotated (
git tag -a). A lightweight tag has no tag object, and the release record keys on that object. - To re-run a release, fix the problem on
mainfirst, then delete the tag locally and remotely and tag again. A tag always runs the workflow file from its own commit, so editing the workflow and re-pushing the same tag changes nothing. - Do not add a publishing step. The pipeline cannot write the record, and the old
sh.tangled.repo.artifactshape is not read by the current indexer, so a step that writes it reports success and produces nothing visible. - A dependency must exist in nixpkgs before you add it to the workflow. A name that does not resolve fails the microvm before any step runs, and it is only exercised the first time a step needs it, which can be releases later.