docs(installer): record Phase 0.3 — the bundle CI and where bundles live #85

wtclaude · 2026-08-04T16:18:35Z

wtclaude commented

2026-08-04 16:18:35 +00:00

Documentation half of installer Phase 0.3. Code PRs: RunicGateway/installer#3, RunicGateway/link#25, RunicGateway/servuo-plugins#9.

Phase 0 item 3 asked for three things — "Compose job (read both repos' latest releases → run the two gates → publish bundle.json), the nightly cron, and the dispatch step appended to each component's release workflow." All three landed, and building them settled questions §7 had left open, so those sections are corrected rather than appended to.

Status

Phase 0 is now all but complete. 0.2 is merged and released as link v1.1.0; 0.3 is in review; 0.4 (INSTALL.md) is the remaining item, and the shape it was waiting on has settled. Every prerequisite in another repo has landed, so what the installer will install is already released and composed — ahead of the binary that installs it.

`installer/PLAN.md`

Phase 0 item 2 → merged, with the release it produced. Item 3 gains an "As built" subsection matching the ones items 1 and 2 already have, recording what was chosen rather than inherited:

Bundles are committed, not released — the one genuinely open question here, decided by the fact that this repo's own releases are the installer binaries.
Why gate 1 reads the sidecar's protocol from source at the release tag rather than asking the binary. --print-config (Phase 0.2) would answer authoritatively, but only for releases from v1.1.0 onward, and --bundle <tag> has to be able to recompose a bundle from an older pair. It also avoids executing a downloaded artifact and provisioning a throwaway config whose auth token would then be sitting in a CI log. A constant that has moved is a hard failure — treating "could not read" as "matches" is how a mismatched pair ships.
Why gate 2 records the hash CI computed itself, and separately checks for assets absent from SHA256SUMS — sha256sum -c passes right over a file the sums file does not mention.
Why release metadata is read anonymously: those are exactly the requests the shipped installer makes on a host with no credentials, so a repo flipped to private fails CI rather than an operator.
Why an unrecognized asset name is a hard failure, and why a run that changes nothing writes nothing.

§7.1 is corrected in two places.

The manifest shape now shows link.assets as a map keyed by platform. The single sha256 this section sketched could only ever have described one of the two binaries link publishes, and the installer runs on both — this is the one place the design as written was simply wrong. Also adds schema/generated and the servuo block, and states that schema, protocol, and the component release versions all move independently.

It also gains a subsection naming where bundles are published: committed under bundles/ in the installer repo, reachable as anonymous raw URLs, with every bundle kept forever so --bundle stays reproducible and same-day bundles disambiguated as 2026.08.04.2. Explicitly not one Gitea release per bundle — that repo's own releases are the installer binaries and /releases/latest returns whichever release is newest regardless of kind, so interleaving would make "latest" intermittently resolve to a release carrying no installer binary.

§7.2 records that the dispatch steps now exist (the servuo-plugins TODO is discharged), and that a failed dispatch is a warning rather than a failed release — which is what keeps write access on the installer repo out of the components' hard credential requirements.

§7.3 records that the releasable-commit rule must also exclude merge commits, whose subject is Merge pull request '<the real subject>'. Without that, merging a docs: branch whose title happens to quote a fix: would re-dispatch a correctly-declining release workflow every night — the exact failure mode this section exists to prevent.

AI-assisted contribution

This PR was written with AI assistance (Claude Code / Claude Opus 5); commits carry the Co-Authored-By trailer.

Documentation half of installer Phase 0.3. Code PRs: RunicGateway/installer#3, RunicGateway/link#25, RunicGateway/servuo-plugins#9. Phase 0 item 3 asked for three things — *"Compose job (read both repos' latest releases → run the two gates → publish `bundle.json`), the nightly cron, and the dispatch step appended to each component's release workflow."* All three landed, and building them **settled questions §7 had left open**, so those sections are corrected rather than appended to. ## Status **Phase 0 is now all but complete.** 0.2 is merged and released as `link` `v1.1.0`; 0.3 is in review; 0.4 (`INSTALL.md`) is the remaining item, and the shape it was waiting on has settled. Every prerequisite in another repo has landed, so *what* the installer will install is already released and composed — ahead of the binary that installs it. ## `installer/PLAN.md` **Phase 0 item 2 → merged**, with the release it produced. **Item 3 gains an "As built" subsection** matching the ones items 1 and 2 already have, recording what was chosen rather than inherited: - **Bundles are committed, not released** — the one genuinely open question here, decided by the fact that this repo's *own* releases are the installer binaries. - **Why gate 1 reads the sidecar's protocol from source at the release tag** rather than asking the binary. `--print-config` (Phase 0.2) would answer authoritatively, but only for releases from `v1.1.0` onward, and `--bundle <tag>` has to be able to recompose a bundle from an older pair. It also avoids executing a downloaded artifact and provisioning a throwaway config whose auth token would then be sitting in a CI log. A constant that has moved is a hard failure — treating "could not read" as "matches" is how a mismatched pair ships. - **Why gate 2 records the hash CI computed itself**, and separately checks for assets *absent* from `SHA256SUMS` — `sha256sum -c` passes right over a file the sums file does not mention. - **Why release metadata is read anonymously**: those are exactly the requests the shipped installer makes on a host with no credentials, so a repo flipped to private fails CI rather than an operator. - **Why an unrecognized asset name is a hard failure**, and why a run that changes nothing writes nothing. **§7.1 is corrected in two places.** The manifest shape now shows `link.assets` as a **map keyed by platform**. The single `sha256` this section sketched could only ever have described one of the two binaries `link` publishes, and the installer runs on both — this is the one place the design as written was simply wrong. Also adds `schema`/`generated` and the `servuo` block, and states that `schema`, `protocol`, and the component release versions all move independently. It also gains a subsection naming **where bundles are published**: committed under `bundles/` in the installer repo, reachable as anonymous raw URLs, with every bundle kept forever so `--bundle` stays reproducible and same-day bundles disambiguated as `2026.08.04.2`. Explicitly **not** one Gitea release per bundle — that repo's own releases are the installer binaries and `/releases/latest` returns whichever release is newest regardless of kind, so interleaving would make "latest" intermittently resolve to a release carrying no installer binary. **§7.2** records that the dispatch steps now exist (the servuo-plugins TODO is discharged), and that a failed dispatch is a **warning rather than a failed release** — which is what keeps write access on the installer repo out of the components' hard credential requirements. **§7.3** records that the releasable-commit rule must also **exclude merge commits**, whose subject is `Merge pull request '<the real subject>'`. Without that, merging a `docs:` branch whose title happens to quote a `fix:` would re-dispatch a correctly-declining release workflow every night — the exact failure mode this section exists to prevent. ## AI-assisted contribution - [x] This PR was written with AI assistance (Claude Code / Claude Opus 5); commits carry the `Co-Authored-By` trailer.

wtclaude added 1 commit 2026-08-04 16:18:37 +00:00

docs(installer): record Phase 0.3 — the bundle CI and where bundles live 10ebce706f

Documentation half of installer Phase 0.3. Code PRs: RunicGateway/installer#3,
RunicGateway/link#25, RunicGateway/servuo-plugins#9.

Phase 0 item 3 asked for a compose job, a nightly cron, and a dispatch step in
each component. All three landed, and building them settled questions §7 had
left open — so those sections are corrected rather than appended to.

Status: Phase 0 is now all but complete. 0.2 is merged and released as link
v1.1.0; 0.3 is in review; 0.4 (INSTALL.md) is the remaining item, and the shape
it was waiting on has settled.

Phase 0 item 3 gains an "As built" subsection matching items 1 and 2, recording
what was chosen rather than inherited: why gate 1 reads the sidecar's protocol
from source at the release tag instead of asking the binary via --print-config
(it only answers for v1.1.0+, and --bundle <tag> must be able to recompose an
older pair); why gate 2 records the hash CI computed itself and separately
checks for assets absent from SHA256SUMS; why release metadata is read
anonymously; why an unrecognized asset name is a hard failure; and why a run
that changes nothing writes nothing.

§7.1 is corrected in two places. The manifest shape now shows link.assets as a
map keyed by platform — the single sha256 this section sketched could only ever
have described one of the two binaries link publishes — plus schema/generated
and the servuo block. And it gains a subsection naming where bundles are
published: committed under bundles/ in the installer repo, NOT one Gitea release
per bundle, because that repo's own releases are the installer binaries and
/releases/latest returns whichever release is newest regardless of kind.

§7.2 records that the dispatch steps now exist, and that a failed dispatch is a
warning rather than a failed release — which is what keeps the installer repo's
token out of the components' hard requirements.

§7.3 records that the releasable-commit rule must also exclude merge commits,
whose subject quotes the real one: without that, merging a docs: branch whose
title mentions a fix: would re-dispatch a declining release workflow nightly.

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

whitlocktech merged commit fc79bb6ed0 into main

2026-08-04 16:20:20 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 16:20:32 +00:00

Merge pull request 'docs(installer): record Phase 0.3 — the bundle CI and where bundles live' (#85) from docs/installer-phase-0.3 into main

whitlocktech deleted branch docs/installer-phase-0.3

2026-08-04 16:20:45 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#85