Devin Foley
8f7b8b3fda
> Follow-up to #11006 (merged): rebased onto master and ready for review. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The release subsystem now publishes canary (every master push), nightly (scheduled, smoke-gated, added in #11006), and stable (manual) > - There is still no human-approved release-candidate lane between nightly and stable, and nothing enforces that a stable actually soaked anywhere before shipping > - Betas need a real approval gate, and stables need a soak policy that is data, not prose > - This pull request adds the beta channel: a manual promotion of a chosen nightly behind the `npm-beta` environment gate, re-smoked after publish, plus a stable preflight that enforces a 3-day beta soak with a written-justification bypass > - The benefit is a complete canary → nightly → beta → stable train where every stable shipped as a beta first, and emergencies leave a written trace ## Linked Issues or Issue Description **Subsystem affected** Release automation: `scripts/release.sh`, `scripts/release-lib.sh`, `.github/workflows/release.yml`, `.github/workflows/docker.yml`, `.github/workflows/release-smoke.yml`. **Problem or motivation** After #11006 the project has canary and nightly prerelease lanes, but no release-candidate lane. Stable promotion has no enforced soak: any ref can ship as stable directly. There is no approval boundary for a broader-audience prerelease, and no structured way to record why an emergency release skipped validation. **Proposed solution** Add a `beta` channel: a manual dispatch that promotes a chosen nightly's source commit, publishes behind the `npm-beta` GitHub environment (required reviewers are the gate), re-smokes the published beta, and tags `beta/vX`. Enforce in the stable path that the source commit shipped as a beta at least 3 days earlier (measured from the beta's npm publish time), with a `skip_soak_justification` input as the recorded emergency bypass. **Alternatives considered** Codifying the soak policy in docs only. Rejected: an unenforced policy decays; the preflight makes the policy executable while the justification input keeps the emergency path usable and auditable. ## What Changed - `scripts/release.sh` + `scripts/release-lib.sh`: `beta` channel — requires HEAD to carry a `nightly/v*` tag, publishes the package set as `YYYY.MDD.P-beta.N` under dist-tag `beta`, tags `beta/vYYYY.MDD.P-beta.N` - `.github/workflows/release.yml`: - `channel: beta` dispatch path: `select_beta` resolves the newest (or an explicit `source_version`) nightly and fails loudly on selection problems; `publish_beta` runs behind the `npm-beta` environment, pushes the tag, and dispatches `docker.yml`; `smoke_beta` re-runs the release smoke suite against the exact published beta version - stable path: new `preflight_stable` job enforces the 3-day beta soak from the beta's npm publish time; `skip_soak_justification` bypasses with the reason echoed into the job summary; dry runs report without blocking - `.github/workflows/docker.yml`: `beta/v*` tags publish `:beta` on both images, with exact version stamping - `.github/workflows/release-smoke.yml`: `beta` added to the dispatch choice list - Docs: `CHANNELS.md` beta entries; `RELEASING.md` beta lane, soak gate, and failure playbook; `RELEASE-AUTOMATION-SETUP.md` `npm-beta` environment setup, including the warning to create the environment before the first beta dispatch (GitHub auto-creates unprotected environments on first reference) - Tests: beta version-counting coverage in `scripts/release-registry-versions.test.mjs`; beta identity and nightly-tag guard coverage in `scripts/__tests__/release-dry-run-notes.test.mjs` ## Verification - `node --test` on the two touched suites: 17 pass, including the 3 new beta tests - `bash -n` on both shell scripts and YAML parse of all three workflows - After merge, in order: create the `npm-beta` environment, dispatch `channel: beta` with `dry_run: true` to preview, then a real promotion of a published nightly through the approval gate, then a stable dry-run against a young beta to see the soak gate report ## Risks - If the `npm-beta` environment does not exist when the first beta dispatch runs, GitHub creates it with no protection rules and the beta publishes without approval. Mitigated by documentation and by creating the environment before merge (operator step) - Until the first beta exists, every stable dispatch requires `skip_soak_justification`. This is deliberate — the first beta ships immediately after this merges — but it is a behavior change to the stable dispatch - The soak clock reads the beta's npm publish time from the registry; a registry outage makes the preflight fall back to requiring justification (fail-closed) ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic) in Claude Code, with extended thinking and full tool use (repository exploration, local test execution, live registry and git verification). All code, tests, and docs in this PR were model-authored under human direction. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (pending — will confirm before merge) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending — will confirm before merge) - [x] I will address all Greptile and reviewer comments before requesting merge
3.8 KiB
Release Channels
Paperclip ships on four channels. Pick the one that matches your appetite for freshness versus stability — switching is just a matter of which version you install.
| Channel | What it is | Updates | npm | Docker |
|---|---|---|---|---|
stable |
The recommended release | every week or two | paperclipai@latest |
ghcr.io/paperclipai/paperclip:latest |
beta |
Release candidates soaking before stable | when promoted | paperclipai@beta |
ghcr.io/paperclipai/paperclip:beta |
nightly |
Yesterday's merges, smoke-tested as a unit | once a night | paperclipai@nightly |
ghcr.io/paperclipai/paperclip:nightly |
canary |
Every merge to master, as it happens |
many times a day | paperclipai@canary |
ghcr.io/paperclipai/paperclip:canary |
Choosing a channel
stable is the right choice for almost everyone. It only moves when a release has been explicitly vetted and promoted by a maintainer, and every stable must first soak as a beta for at least 3 days.
beta is for people who want the next stable early. A beta is a nightly that a maintainer hand-picked and explicitly promoted behind an approval gate, and it is re-smoked after publishing. Betas are the release candidates: what you run on beta today is what stable becomes a few days later.
nightly is for people who want new features quickly but not the churn of tracking every merge. Once a night, the newest master build that published green is run through the full release smoke suite (real Docker container, real onboarding flow, browser-driven). Only if that passes does it ship as the nightly. If smoke fails, there is no nightly that night — the channel never ships a build that failed its checks.
canary is the bleeding edge: it publishes on every merge to master.
It is primarily the lane that continuously exercises our release automation,
but it's available to anyone who wants the newest bits and accepts the risk.
Installing from a channel
npm / npx:
npx paperclipai@latest onboard # stable
npx paperclipai@beta onboard
npx paperclipai@nightly onboard
npx paperclipai@canary onboard
Docker:
docker pull ghcr.io/paperclipai/paperclip:latest # stable
docker pull ghcr.io/paperclipai/paperclip:beta
docker pull ghcr.io/paperclipai/paperclip:nightly
docker pull ghcr.io/paperclipai/paperclip:canary
Every image is also published as :sha-<short-sha> for exact pinning, and
stable images additionally get :YYYY.MDD.P version tags.
Switching channels
Channel choice is per-install: install from a different tag and you're on that channel. Moving forward (stable → nightly) is always safe. Moving backward (nightly → stable) can mean running an older schema than your data was created with — treat a downgrade like a restore and keep a backup of your data directory before switching down.
Reading version strings
The version tells you which channel a build came from:
2026.807.0— stable, published Aug 7 20262026.807.0-beta.0— beta promoted on Aug 7 20262026.807.0-nightly.0— nightly cut on Aug 7 20262026.807.0-canary.4— the fifth canary for the Aug 7 line
Each promotion republishes the exact source commit of the previous lane's build: a nightly shares its source SHA with a canary, and a beta with a nightly. The version dates the promotion, and the shared SHA is visible in the release job summaries and as git tags on the commit.
One quirk to be aware of: npm's semver ordering compares prerelease names
alphabetically, so -beta.N sorts below -canary.N, which sorts below
-nightly.N for the same base version. This never matters when installing by
dist-tag (the recommended way), only if you write version ranges by hand.
For maintainers
The publishing mechanics, promotion flow, and release checklist live in
RELEASING.md.