docs(installer): bundles publish to a branch, releases only tag #97

wtclaude · 2026-08-05T22:22:46Z

wtclaude commented

2026-08-05 22:22:46 +00:00

What & why

Two corrections to §7.1, both forced by the first compose run that ever had a bundle to write (task 542), and both settled by the org lead on 2026-08-05.

What the section claimed

Committing … needs no new branch-protection exception: release.yml's version-bump commit already requires the CI user to be able to push to main.

Both halves were wrong.

main is protected and declines the push — pre-receive hook declined, on the initial attempt and again on the rebase-retry. And release.yml had never pushed anything: its bump step has never executed in any repo carrying it, because an empty template expression written literally in one of its comments makes the runner fail to build the step and skip it without failing the job. The tags exist because Gitea's release API creates one when it publishes.

So the assumption that a working push path already existed had never been tested by anything — which is the part worth recording, more than the fix.

What replaces it

Bundles publish to a bundles branch at its root. That keeps every property the original choice was for — a reviewable diff, a git history of the compat matrix, plain anonymous raw URLs, no credentials on the shard host — and needs no exception at all. Whitelisting a scheduled job for pushes to the default branch would buy nothing this does not.

The release workflows become tag-only for the same reason, as servuo-plugins has always been: the tag is the version. The version is still written into Cargo.toml before building, so a released binary self-reports correctly; it is no longer committed back, and the next version is computed from the newest tag. A first release must not depend on a write to a protected branch.

Also updated: the raw URL in INSTALL.md Appendix A1 (the by-hand path), and Phase 0.3's as-built note, which recorded the original decision.

How it was tested

Prose, but each claim is an observation from today rather than a recollection: the rejected push and the interpolation error are both in the compose job's log, link's Cargo.toml is still 0.1.0 at tag v1.1.1, servuo-plugins' log shows * [new tag] v0.2.0 -> v0.2.0 going through the same protection, and the bundles branch is live and anonymously readable at the URL this section now documents.

Code PRs this describes

installer#13 (publish to the branch, plus the stale-check fix and the required linux-aarch64 key), installer#14 and link#28 (tag-only releases), installer#15 (the crate's BUNDLE_BASE).

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Two corrections to §7.1, both forced by the first compose run that ever had a bundle to write (task 542), and both settled by the org lead on 2026-08-05. ### What the section claimed > Committing … needs no new branch-protection exception: `release.yml`'s version-bump commit already requires the CI user to be able to push to `main`. **Both halves were wrong.** `main` is protected and declines the push — `pre-receive hook declined`, on the initial attempt and again on the rebase-retry. And `release.yml` had never pushed anything: its bump step **has never executed in any repo carrying it**, because an empty template expression written literally in one of its comments makes the runner fail to build the step and skip it *without failing the job*. The tags exist because Gitea's release API creates one when it publishes. So the assumption that a working push path already existed had never been tested by anything — which is the part worth recording, more than the fix. ### What replaces it Bundles publish to a **`bundles` branch** at its root. That keeps every property the original choice was for — a reviewable diff, a git history of the compat matrix, plain anonymous raw URLs, no credentials on the shard host — and needs no exception at all. Whitelisting a scheduled job for pushes to the default branch would buy nothing this does not. The release workflows become **tag-only** for the same reason, as `servuo-plugins` has always been: the tag *is* the version. The version is still written into `Cargo.toml` before building, so a released binary self-reports correctly; it is no longer committed back, and the next version is computed from the newest tag. A first release must not depend on a write to a protected branch. Also updated: the raw URL in `INSTALL.md` Appendix A1 (the by-hand path), and Phase 0.3's as-built note, which recorded the original decision. ## How it was tested Prose, but each claim is an observation from today rather than a recollection: the rejected push and the interpolation error are both in the compose job's log, `link`'s `Cargo.toml` is still `0.1.0` at tag `v1.1.1`, `servuo-plugins`' log shows `* [new tag] v0.2.0 -> v0.2.0` going through the same protection, and the `bundles` branch is live and anonymously readable at the URL this section now documents. ## Code PRs this describes installer#13 (publish to the branch, plus the stale-check fix and the required `linux-aarch64` key), installer#14 and link#28 (tag-only releases), installer#15 (the crate's `BUNDLE_BASE`). ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-05 22:22:48 +00:00

docs(installer): bundles publish to a branch, releases only tag ddcfb5de29

Two corrections to §7.1, both forced by the first compose run that ever
had a bundle to write (org lead, 2026-08-05).

The section said bundles are committed to `main` and that this "needs no
new branch-protection exception: release.yml's version-bump commit
already requires the CI user to be able to push to main". Both halves
were wrong. `main` is protected and declines the push, and release.yml
had never pushed anything: its bump step has never executed in any repo
carrying it, because an empty template expression written literally in
one of its comments makes the runner fail to build the step and skip it
without failing the job. The tags exist because Gitea's release API
creates one when it publishes. The assumption that a working push path
already existed had never been tested by anything.

Bundles now publish to a `bundles` branch at its root, which keeps every
property the original choice was for -- reviewable diff, git history of
the compat matrix, plain anonymous raw URLs, no credentials on the shard
host -- and needs no exception. The release workflows are tag-only for
the same reason, as servuo-plugins has always been: the version is still
written into Cargo.toml before building so a released binary
self-reports correctly, but is not committed back.

Also updated: the raw URLs in INSTALL.md Appendix A1 and in Phase 0.3's
as-built note.

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

whitlocktech merged commit 4a35e86bc8 into main

2026-08-07 19:15:35 +00:00

whitlocktech deleted branch docs/bundles-branch

2026-08-07 19:15:36 +00:00

whitlocktech referenced this issue from a commit

2026-08-07 19:15:39 +00:00

Merge pull request 'docs(installer): bundles publish to a branch, releases only tag' (#97) from docs/bundles-branch into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#97