diff --git a/CLAUDE.md b/CLAUDE.md index 9ed4aba4d0..b6ecb7ef7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -106,9 +106,14 @@ Repo dev commands use checkout-local state by default. In this checkout, `PASEO_ See [docs/development.md](docs/development.md) for full setup, build sync requirements, and debugging. -## Critical rules +## Release branches -- **Before changing the plugin SDK, compiler, host module maps, scaffold, or examples, read [SDK import boundaries](docs/plugins.md#sdk-import-boundaries).** Classify the export by runtime first and preserve the enforced boundaries. +When the user says "this goes to next", create or +retarget the PR to `next` and preserve that destination through delivery. Follow +[release branch discipline](docs/release.md#release-branch-discipline) for creating +and updating `next`, integrating it after a release, and releasing a hotfix from a tag. + +## Critical rules - **NEVER restart the main Paseo daemon on port 6767 without permission** — it manages all running agents. If you're an agent, restarting it kills your own process. - **NEVER assume a timeout means the service needs restarting** — timeouts can be transient. diff --git a/docs/release.md b/docs/release.md index 52b0f17ac2..e66b8e6fbb 100644 --- a/docs/release.md +++ b/docs/release.md @@ -47,6 +47,36 @@ commit the prepared inputs locally and run the release command. Its branch and tag push is the one remote release batch and starts CI for the complete release commit. +## Release branch discipline + +While you finalize a release on `main`, use a temporary `next` branch for work intended for the following +release. This applies to both beta and stable releases. + +- Create each new `next` from freshly fetched `origin/main`. Reuse it while active. +- "This goes to next" means create the PR against `next` or retarget an existing + PR, and keep that destination through delivery. +- Keep `next` current by merging `origin/main` into it as release fixes land. + Avoid rebasing this shared branch because agents and open PRs depend on its history. +- After the release ships, bring `next` up to date and open a `next` → `main` PR. + Pass CI and merge without squashing away the individual PR commits needed for + the changelog. Retarget remaining PRs based on `next` to `main` and delete the integrated + `next`. Create it fresh when needed again. + +**Setup still needed:** CI, Docker, and Nix PR checks currently target only `main`, +and GitHub permits only squash merges. Enable checks and required-check protection +for `next`, CI on its pushes, and merge commits for the integration PR. Handle PR +base changes (`edited` events) so retargeting runs checks against the new base; +GitHub's default PR events do not cover this. Deployment triggers stay unchanged. + +### Hotfix from a release tag + +If `main` contains changes you do not want to release, branch from the affected +release tag and cherry-pick only the required fixes. Run CI on that branch, then +use the normal release flow with it as the explicit source, choosing a new patch +or beta version. Ensure the fixes and changelog also reach `main` and any active +`next`, preserving newer development and version changes there. This is a +short-lived hotfix branch, not another maintained release track. + ## ACP catalog updates ACP catalog work enters a release through an explicit user request: @@ -64,7 +94,7 @@ release push as the changelog and version commit. There are two supported release paths: -1. **Direct stable release**: you are ready to ship the current `main` commit to everyone immediately. +1. **Direct stable release**: you are ready to ship the resolved release source to everyone immediately (default `origin/main`). 2. **Beta flow**: release candidates on the `beta` channel. Each beta carries its own changelog entry, publishes npm only on the explicit `beta` dist-tag, and stays behind the Stable/Beta switch on `/download`. Paseo has one linear release track even though npm dist-tags are independent