mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 16:11:46 +02:00
Devin Foley
1ea2f0e2d6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The release channels (canary → nightly → beta → stable) select by install target, and users discover them today only through maintainer-oriented docs > - A user who wants to know "which lane am I on, and what else is there" has no self-serve answer > - The channel rollout planned a read-only CLI command for exactly this > - This pull request adds `paperclipai channels`: every lane with the version its dist-tag resolves to, the install command for it, and which lane the running install follows > - The benefit is self-serve lane discovery without reading release documentation ## Linked Issues or Issue Description Refs #11008 — the user-facing discovery surface for the channel model completed there. **Subsystem affected** CLI: `cli/src/commands/channels.ts` (new), `cli/src/index.ts`, `doc/CHANNELS.md`, tests. **Problem or motivation** Channel selection is install-based (`@latest` / `@beta` / `@nightly` / `@canary`), but nothing in the product tells a user which channel their install follows or what the other lanes currently resolve to. The information lives in `doc/CHANNELS.md` and the npm registry, neither of which a running install surfaces. **Proposed solution** A read-only `paperclipai channels` command: prints each channel with the version its dist-tag currently resolves to (per-lane registry lookups that degrade to `unavailable` individually), the install command for each, and the running install's lane parsed from its version suffix — source checkouts carry the repository's placeholder version and are reported as unmapped rather than guessed. `--json` emits the same data for scripting. ## What Changed - `cli/src/commands/channels.ts` (new): channel table, lane parsing, registry resolution, human and `--json` output - `cli/src/index.ts`: registers `channels` - `doc/CHANNELS.md`: "Seeing where you are" section - `cli/src/__tests__/channels.test.ts` (new): lane parsing including unknown versions, full resolution against a fake runner, per-lane degradation, table/dist-tag sync ## Verification - `vitest run cli/src/__tests__/channels.test.ts`: 5 pass - `pnpm typecheck` in `cli/` - Live run against the real registry shows all four lanes with their current versions (`2026.722.0` / `2026.811.0-beta.0` / `2026.811.0-nightly.0` / canary) and correctly reports a source checkout as unmapped ## Risks - Low. Read-only command reusing the existing `resolvePublishedVersion` registry helper; no state, no auth, no publish surface ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic) in Claude Code, with extended thinking and full tool use. All changes 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
100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
npx paperclipai@latest onboard # stable
|
|
npx paperclipai@beta onboard
|
|
npx paperclipai@nightly onboard
|
|
npx paperclipai@canary onboard
|
|
```
|
|
|
|
Docker:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Seeing where you are
|
|
|
|
```bash
|
|
npx paperclipai channels
|
|
```
|
|
|
|
prints every channel with the version it currently resolves to, the install
|
|
command for each, and which channel your install follows (with `--json` for
|
|
scripting).
|
|
|
|
## 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 2026
|
|
- `2026.807.0-beta.0` — beta promoted on Aug 7 2026
|
|
- `2026.807.0-nightly.0` — nightly cut on Aug 7 2026
|
|
- `2026.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`](RELEASING.md).
|