The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(release): draft stable notes at beta publish, read them from master at promotion (#11567)
Devin Foley664052f8ea17
diff --git a/.agents/skills/release-changelog-discord-message/SKILL.md b/.agents/skills/release-changelog-discord-message/SKILL.mdindex 9ae7972d09..7852ad1a83 100644--- a/.agents/skills/release-changelog-discord-message/SKILL.md+++ b/.agents/skills/release-changelog-discord-message/SKILL.md@@ -11,7 +11,11 @@ description: >Write the Discord release announcement for the **stable** Paperclip release.This is the companion to `.agents/skills/release-changelog/SKILL.md`. That skill-generates the file at `releases/vYYYY.MDD.P.md`. This skill turns that file into+writes the changelog — during the beta soak it lives at+`releases/beta/v{beta-version}.md` on the `release-notes/v{beta-version}`+branch, and after the stable ships a canonicalization PR renames it to+`releases/vYYYY.MDD.P.md` (see that skill's Channel Process section). This+skill turns that file intoa single copy-pasteable Discord block, in dotta's voice, and posts it as the`discord_announcement` document on the release issue.@@ -27,8 +31,9 @@ current Paperclip work — not invented.## When to use-- After `release-changelog` has produced `releases/vYYYY.MDD.P.md` on the- release worktree/PR.+- After `release-changelog` has produced the changelog (beta-keyed on the+ `release-notes/v{beta-version}` branch during the soak, or the+ canonicalized `releases/vYYYY.MDD.P.md` after the stable ships).- When the release issue (the one assigned by the release routine) asks for aDiscord announcement, or has a `discord_announcement` document that needs tobe refreshed for a new date/version.@@ -123,6 +128,12 @@ Notes on the template:- The opening and closing `:paperclip: :paperclip: :paperclip:` bookends arepart of the brand — keep them.+- Name the install channels somewhere in the post: `npx paperclipai@latest`+ for the stable, `@beta` / `@nightly` / `@canary` for earlier access, and+ Docker `:latest` moving **only** on stable releases.+- The FULL RELEASE NOTES link points at `releases/v{VERSION}.md` on+ `master` — that file exists only after the post-stable canonicalization+ PR merges. Merge it before the announcement is posted.- Sections may be UPPERCASE or Title Case — dotta has used both. Pick a styleand stay consistent within a single post.- Use `||@everyone||` (Discord spoiler-wrapped) at the very end so it pings@@ -175,15 +186,19 @@ Mimic this register; do not invent a "professional" tone.## Workflow-1. Read the matching `releases/vYYYY.MDD.P.md` produced by `release-changelog`.- Use the version and contributor list from that file — never re-derive them.+1. Read the matching changelog produced by `release-changelog` — the+ beta-keyed file during the soak, `releases/vYYYY.MDD.P.md` once+ canonicalized. Use the version and contributor list from that file —+ never re-derive them.2. Resolve the parent `release` case with key `paperclip-release:vYYYY.MDD.P`.If it does not exist and Cases are enabled, create it using the schema in`.agents/skills/release-changelog/SKILL.md` before creating child cases.3. Read the **release issue thread** (the one assigned to you that ran therelease routine) — comments + linked issues + recent issues in the company- are the source for `WHATS NEXT` and `What's on my mind`. Pull real themes,- not invented ones.+ are the source for `WHATS NEXT` and `What's on my mind`. Commits already+ on `origin/master` **after** the beta source commit are prime "what's+ next" material: they are literally the next release's content. Pull real+ themes, not invented ones.4. Re-read the three verbatim examples below — they're the canonical voice.5. Draft the announcement using the template above.6. PUT it as the `discord_announcement` document on the release issue (seediff --git a/.agents/skills/release-changelog/SKILL.md b/.agents/skills/release-changelog/SKILL.mdindex e428969fdd..da1d141d33 100644--- a/.agents/skills/release-changelog/SKILL.md+++ b/.agents/skills/release-changelog/SKILL.md@@ -32,14 +32,57 @@ Important rules:- do not derive versions from semver bump types- do not create canary changelog files+## Channel Process — Source Commit and File Location++Stables promote a **soaked beta**, so the changelog describes the beta's+source commit, not the tip of `master`:++- The release **source** is the commit the newest `beta/v<beta-version>`+ tag points at (`{beta-src}` below). Resolve it with:++ ```bash+ git fetch origin --tags+ npm view paperclipai dist-tags # the beta dist-tag names the version+ git rev-parse 'beta/v{beta-version}^{commit}'+ ```++- Commits on `master` after `{beta-src}` ship in the **next** release.+ Never include them; they are input for a "what's next" section, not the+ changelog.+- During the soak, the file lives at `releases/beta/v{beta-version}.md`+ on the branch `release-notes/v{beta-version}` (PR to `master`). The+ release workflow pushes that branch with a generated skeleton when the+ beta publishes; work on it and rewrite the skeleton in place. If the+ branch does not exist (a beta cut before the automation), create it+ from `origin/master` and seed the skeleton:++ ```bash+ ./scripts/draft-stable-notes.sh {beta-version}+ ```++- The PR must merge to `master` **before** the stable is dispatched: the+ stable preflight reads the file from `master` and fails without it.+- Never create `releases/vYYYY.MDD.P.md` yourself on this path — after+ the stable ships, the workflow opens a canonicalization PR that renames+ the beta-keyed file to it.+- **Fix path exception** (patch releases from a `candidate/release-*`+ branch): there the notes *do* go directly on the candidate branch as+ `releases/vYYYY.MDD.P.md`, committed alongside the cherry-picked fixes.+## Step 0 — Idempotency Check-Before generating anything, check whether the file already exists:+Before generating anything, check whether the changelog already exists:```bash-ls releases/vYYYY.MDD.P.md 2>/dev/null+ls releases/beta/v{beta-version}.md 2>/dev/null # soak-window home+ls releases/vYYYY.MDD.P.md 2>/dev/null # canonicalized / fix path+git ls-remote origin 'refs/heads/release-notes/v{beta-version}'```+A `release-notes/v{beta-version}` branch holding only the generated+skeleton is the normal starting state, not a conflict — rewrite it in+place.+If it exists:1. read it first@@ -49,13 +92,17 @@ If it exists:## Step 1 — Determine the Stable Range-Find the last stable tag:+Find the last stable tag and the beta source commit:```bashgit tag --list 'v*' --sort=-version:refname | head -1-git log v{last}..HEAD --oneline --no-merges+beta_src="$(git rev-parse 'beta/v{beta-version}^{commit}')"+git log v{last}..${beta_src} --oneline --no-merges```+The changelog range is always `v{last}..{beta-src}` — never `..HEAD` and+never `..origin/master`.+The stable version comes from one of:- an explicit maintainer request@@ -76,8 +123,8 @@ Collect release data from:Useful commands:```bash-git log v{last}..HEAD --oneline --no-merges-git log v{last}..HEAD --format="%H %s" --no-merges+git log v{last}..{beta-src} --oneline --no-merges+git log v{last}..{beta-src} --format="%H %s" --no-mergesls .changeset/*.md | grep -v README.mdgh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels```@@ -94,10 +141,10 @@ Look for:Key commands:```bash-git diff --name-only v{last}..HEAD -- packages/db/src/migrations/-git diff v{last}..HEAD -- packages/db/src/schema/-git diff v{last}..HEAD -- server/src/routes/ server/src/api/-git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true+git diff --name-only v{last}..{beta-src} -- packages/db/src/migrations/+git diff v{last}..{beta-src} -- packages/db/src/schema/+git diff v{last}..{beta-src} -- server/src/routes/ server/src/api/+git log v{last}..{beta-src} --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true```If breaking changes are detected, flag them prominently — they must appear in the@@ -143,6 +190,14 @@ Rules:## Step 5 — Write the File+The **file path** is the beta-keyed one from the Channel Process section+(`releases/beta/v{beta-version}.md`), but the **content** is titled with+the planned stable version. Resolve it with+`./scripts/release.sh stable --date {planned-promotion-date} --print-version`+(promotion is normally the beta publish date plus the 3-day soak). If the+promotion date slips, the version re-resolves at dispatch — the beta-keyed+filename makes that harmless; refresh the title when it happens.+The opening line of the changelog must be an H1 of the format `# Paperclip {version}`(no braces), e.g. `# Paperclip v2026.618.0`. Always include the `Paperclip ` prefix andthe `v` on the version.@@ -177,7 +232,7 @@ The `Contributors` section should always be included. List every person who authcommits in the release range, @-mentioning them by their **GitHub username** (not theirreal name or email). To find GitHub usernames:-1. Extract usernames from merge commit messages: `git log v{last}..HEAD --oneline --merges` — the branch prefix (e.g. `from username/branch`) gives the GitHub username.+1. Extract usernames from merge commit messages: `git log v{last}..{beta-src} --oneline --merges` — the branch prefix (e.g. `from username/branch`) gives the GitHub username.2. For noreply emails like `[email protected]`, the username is the part before `@`.3. For contributors whose username is ambiguous, check `gh api users/{guess}` or the PR page.diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 7915921ba8..3f0e1e98a6 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -621,6 +621,67 @@ jobs:} >> "$GITHUB_STEP_SUMMARY"gh workflow run docker.yml --ref "refs/tags/${tag}" --repo "$GITHUB_REPOSITORY"+ # Draft the eventual stable's release notes the moment the beta exists:+ # the promoted bits are frozen now, and the 3-day soak is the natural+ # review window. The draft lands on a machine-owned branch; a human opens+ # and merges the PR, because a PR created with GITHUB_TOKEN would not+ # trigger the pr.yml checks a merge requires.+ draft_stable_notes:+ needs: [select_beta, publish_beta]+ if: ${{ !cancelled() && !inputs.dry_run && needs.publish_beta.result == 'success' }}+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ contents: write+ steps:+ - name: Checkout repository+ uses: actions/checkout@v7+ with:+ ref: master+ fetch-depth: 0++ - name: Configure git author+ run: |+ git config user.name "github-actions[bot]"+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"++ - name: Draft stable notes from the published beta+ env:+ BETA_VERSION: ${{ needs.publish_beta.outputs.beta_version }}+ SOURCE_SHA: ${{ needs.select_beta.outputs.sha }}+ run: |+ set -euo pipefail+ git fetch origin --tags --quiet+ # A rejected beta tag push (the workflows-permission case) leaves+ # the tag absent from origin while npm already has the beta;+ # recreate it locally so drafting does not block on the manual+ # tag recovery.+ if ! git rev-parse --verify "refs/tags/beta/v${BETA_VERSION}" >/dev/null 2>&1; then+ git tag "beta/v${BETA_VERSION}" "${SOURCE_SHA}"+ fi+ ./scripts/draft-stable-notes.sh "${BETA_VERSION}"++ - name: Push the draft branch+ env:+ BETA_VERSION: ${{ needs.publish_beta.outputs.beta_version }}+ run: |+ set -euo pipefail+ branch="release-notes/v${BETA_VERSION}"+ git checkout -B "$branch"+ git add "releases/beta/v${BETA_VERSION}.md"+ git commit -m "docs(release): draft stable notes for beta ${BETA_VERSION}"+ # Machine-owned branch: force push so a re-run regenerates cleanly.+ git push -f origin "$branch"+ {+ echo "## Stable notes draft pushed"+ echo ""+ echo "- Branch: \`${branch}\`"+ echo "- Open the PR (a human opens it so CI runs):"+ echo " https://github.com/${GITHUB_REPOSITORY}/compare/master...${branch}?expand=1"+ echo "- Edit it during the soak. The stable promotion reads"+ echo " \`releases/beta/v${BETA_VERSION}.md\` from master."+ } >> "$GITHUB_STEP_SUMMARY"+# Post-publish verification: run the release smoke suite against the exact# beta version that was just published.#@@ -656,6 +717,11 @@ jobs:contents: readoutputs:sha: ${{ steps.soak.outputs.sha }}+ beta_version: ${{ steps.soak.outputs.beta_version }}+ stable_version: ${{ steps.notes.outputs.stable_version }}+ notes_mode: ${{ steps.notes.outputs.notes_mode }}+ notes_path: ${{ steps.notes.outputs.notes_path }}+ notes_ref: ${{ steps.notes.outputs.notes_ref }}steps:- name: Checkout repositoryuses: actions/checkout@v7@@ -724,6 +790,7 @@ jobs:fibeta_version="${beta_tag#beta/v}"+ echo "beta_version=${beta_version}" >> "$GITHUB_OUTPUT"publish_time="$(npm view "paperclipai@${beta_version}" time --json 2>/dev/null \| node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{const t=JSON.parse(d);process.stdout.write(typeof t === "string" ? t : (t[process.argv[1]] ?? ""))})' "$beta_version" || true)"if [ -z "$publish_time" ]; then@@ -747,6 +814,58 @@ jobs:echo "- Soak time: ${age_days} days"} >> "$GITHUB_STEP_SUMMARY"+ # The stable notes need not exist inside the promoted source commit:+ # a promoted beta's notes are drafted on master (releases/beta/v*.md)+ # at beta-publish time and edited during the soak. Resolve which copy+ # publish_stable should read, and fail early — before the npm-stable+ # approval gate — when none exists. Notes inside the source tree+ # (the candidate fix path) take precedence.+ - name: Resolve stable release notes+ id: notes+ env:+ SHA: ${{ steps.soak.outputs.sha }}+ BETA_VERSION: ${{ steps.soak.outputs.beta_version }}+ STABLE_DATE: ${{ inputs.stable_date }}+ DRY_RUN: ${{ inputs.dry_run }}+ run: |+ set -euo pipefail++ # Pin the master revision the notes were resolved at, so the+ # publish and canonicalization steps read the same content even+ # when master advances during the approval delay.+ echo "notes_ref=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"++ args=(stable --print-version)+ if [ -n "${STABLE_DATE}" ]; then+ args+=(--date "${STABLE_DATE}")+ fi+ version="$(./scripts/release.sh "${args[@]}")"+ echo "stable_version=${version}" >> "$GITHUB_OUTPUT"++ if git cat-file -e "${SHA}:releases/v${version}.md" 2>/dev/null; then+ echo "notes_mode=source_tree" >> "$GITHUB_OUTPUT"+ echo "notes_path=releases/v${version}.md" >> "$GITHUB_OUTPUT"+ echo "- Stable notes: \`releases/v${version}.md\` at the source commit" >> "$GITHUB_STEP_SUMMARY"+ exit 0+ fi++ if [ -n "${BETA_VERSION}" ] && [ -f "releases/beta/v${BETA_VERSION}.md" ]; then+ echo "notes_mode=master_beta" >> "$GITHUB_OUTPUT"+ echo "notes_path=releases/beta/v${BETA_VERSION}.md" >> "$GITHUB_OUTPUT"+ echo "- Stable notes: \`releases/beta/v${BETA_VERSION}.md\` on master" >> "$GITHUB_STEP_SUMMARY"+ exit 0+ fi++ msg="no release notes found for stable ${version}: neither releases/v${version}.md at the source commit nor releases/beta/v${BETA_VERSION:-<beta>}.md on master. Merge the notes PR from the beta's draft branch (release-notes/v<beta-version>), or add the file to the source ref."+ if [ "${DRY_RUN}" = "true" ]; then+ echo "::warning::${msg}"+ echo "- Stable notes: MISSING (a real release would be blocked)" >> "$GITHUB_STEP_SUMMARY"+ echo "notes_mode=missing" >> "$GITHUB_OUTPUT"+ exit 0+ fi+ echo "::error::${msg}"+ exit 1+verify_stable:if: github.event_name == 'workflow_dispatch' && inputs.channel == 'stable'needs: preflight_stable@@ -806,6 +925,8 @@ jobs:contents: writeid-token: writeactions: write+ outputs:+ stable_version: ${{ steps.tag.outputs.version }}steps:- name: Checkout repository@@ -836,6 +957,22 @@ jobs:git config user.name "github-actions[bot]"git config user.email "41898282+github-actions[bot]@users.noreply.github.com"+ # A promoted beta's notes live on master (drafted at beta publish,+ # edited during the soak), not inside the promoted source commit — a+ # commit cannot carry a file named for a promotion date that was+ # unknown when it was created. Materialize them outside the worktree+ # so release.sh still runs against a clean source checkout.+ - name: Materialize stable release notes from master+ if: needs.preflight_stable.outputs.notes_mode == 'master_beta'+ env:+ NOTES_REF: ${{ needs.preflight_stable.outputs.notes_ref }}+ NOTES_PATH: ${{ needs.preflight_stable.outputs.notes_path }}+ run: |+ set -euo pipefail+ git fetch origin master --quiet+ git show "${NOTES_REF}:${NOTES_PATH}" > "$RUNNER_TEMP/stable-notes.md"+ echo "STABLE_NOTES_FILE=$RUNNER_TEMP/stable-notes.md" >> "$GITHUB_ENV"+- name: Publish stableenv:GITHUB_ACTIONS: "true"@@ -844,6 +981,9 @@ jobs:if [ -n "${{ inputs.stable_date }}" ]; thenargs+=(--date "${{ inputs.stable_date }}")fi+ if [ -n "${STABLE_NOTES_FILE:-}" ]; then+ args+=(--notes-file "$STABLE_NOTES_FILE")+ fi./scripts/release.sh "${args[@]}"- name: Dump npm debug logs@@ -857,12 +997,14 @@ jobs:done- name: Push stable tag+ id: tagrun: |tag="$(git tag --points-at HEAD | grep '^v' | head -1)"if [ -z "$tag" ]; thenecho "Error: no stable tag points at HEAD after release." >&2exit 1fi+ echo "version=${tag#v}" >> "$GITHUB_OUTPUT"if ! git push origin "refs/tags/${tag}"; thensha="$(git rev-parse HEAD)"{@@ -913,4 +1055,59 @@ jobs:echo "Error: no v* tag points at HEAD after stable release." >&2exit 1fi- ./scripts/create-github-release.sh "$version"+ args=("$version")+ if [ -n "${STABLE_NOTES_FILE:-}" ]; then+ args+=(--notes-file "$STABLE_NOTES_FILE")+ fi+ ./scripts/create-github-release.sh "${args[@]}"++ # After a stable ships from master-side beta notes, move the file to its+ # canonical home (releases/vYYYY.MDD.P.md) so the stable-notes invariant+ # holds durably. Machine-owned branch + human-opened PR, as with the+ # draft job above.+ canonicalize_stable_notes:+ needs: [preflight_stable, publish_stable]+ if: ${{ needs.preflight_stable.outputs.notes_mode == 'master_beta' && needs.publish_stable.result == 'success' }}+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ contents: write+ steps:+ - name: Checkout repository+ uses: actions/checkout@v7+ with:+ ref: master+ fetch-depth: 0++ - name: Configure git author+ run: |+ git config user.name "github-actions[bot]"+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"++ - name: Push the canonicalization branch+ env:+ STABLE_VERSION: ${{ needs.publish_stable.outputs.stable_version }}+ NOTES_PATH: ${{ needs.preflight_stable.outputs.notes_path }}+ NOTES_REF: ${{ needs.preflight_stable.outputs.notes_ref }}+ run: |+ set -euo pipefail+ branch="release-notes/v${STABLE_VERSION}-canonicalize"+ git checkout -B "$branch"+ # Canonicalize exactly what shipped: take the notes at the pinned+ # revision the release read them from, so a master edit made+ # during the run surfaces as a reviewable diff in this PR instead+ # of silently diverging from the published GitHub Release.+ git show "${NOTES_REF}:${NOTES_PATH}" > "releases/v${STABLE_VERSION}.md"+ git add "releases/v${STABLE_VERSION}.md"+ if git ls-files --error-unmatch "${NOTES_PATH}" >/dev/null 2>&1; then+ git rm -q "${NOTES_PATH}"+ fi+ git commit -m "docs(release): canonicalize stable notes for v${STABLE_VERSION}"+ git push -f origin "$branch"+ {+ echo "## Stable notes canonicalization pushed"+ echo ""+ echo "- Branch: \`${branch}\`"+ echo "- Open and merge the PR (a human opens it so CI runs):"+ echo " https://github.com/${GITHUB_REPOSITORY}/compare/master...${branch}?expand=1"+ } >> "$GITHUB_STEP_SUMMARY"diff --git a/doc/RELEASE-CHECKLIST.md b/doc/RELEASE-CHECKLIST.mdindex 3ab74932a8..e8d3c03245 100644--- a/doc/RELEASE-CHECKLIST.md+++ b/doc/RELEASE-CHECKLIST.md@@ -36,6 +36,11 @@ Happy path:- [ ] `npm view paperclipai@beta version` shows the new `-beta.N`- [ ] `beta/v*` tag pushed; `:beta` and `:beta-cloud` images built- [ ] post-publish smoke (`smoke_beta`) is green+- [ ] `draft_stable_notes` pushed `release-notes/v<beta-version>`; open the+ notes PR from the job-summary link+- [ ] during the soak: edit the notes PR into release voice and merge it+ (the stable promotion reads `releases/beta/v<beta-version>.md` from+ `master`)Fix path (cherry-picked candidate):@@ -50,7 +55,8 @@ Fix path (cherry-picked candidate):- [ ] pick the beta to promote; its source commit is `source_ref`- [ ] the beta has soaked ≥ 3 days with no open beta-blocker issues-- [ ] author `releases/vYYYY.MDD.P.md` on that source ref+- [ ] the beta's notes PR (`releases/beta/v<beta-version>.md`) is merged on+ `master` — preflight fails, before the approval gate, without it- [ ] dispatch `release.yml` with `channel: stable` (a dry run first showsthe resolved version and soak state without publishing)- [ ] approve the `npm-stable` environment gate@@ -59,10 +65,15 @@ Fix path (cherry-picked candidate):versioned Docker tags built- [ ] if the soak gate was bypassed, `skip_soak_justification` carries areal written reason (it lands in the job summary)+- [ ] open and merge the canonicalization PR+ (`release-notes/v<version>-canonicalize`) so the notes land at+ `releases/vYYYY.MDD.P.md`Fix path: `candidate/release-<target>` from the beta's source commit; thesoak gate will demand a justification because the exact bits were not-soaked — write one that stands on its own.+soaked — write one that stands on its own. A candidate branch carries its+own `releases/vYYYY.MDD.P.md` (preflight prefers source-tree notes), so+author the notes as a commit on the candidate.## After any incomplete rundiff --git a/doc/RELEASING.md b/doc/RELEASING.mdindex 1e1891663d..3eb0059316 100644--- a/doc/RELEASING.md+++ b/doc/RELEASING.md@@ -10,7 +10,10 @@ The release model is now commit-driven:3. Betas are manual, human-approved promotions of a chosen nightly.4. Stable releases promote a beta that has soaked for at least 3 days(bypass requires a written justification).-5. Stable release notes live in `releases/vYYYY.MDD.P.md`.+5. Stable release notes live in `releases/vYYYY.MDD.P.md`. They are+ drafted automatically when a beta is published (as+ `releases/beta/v<beta-version>.md` on `master`), edited during the+ soak, and moved to the versioned name after the stable ships.6. Only stable releases get GitHub Releases.The user-facing guide to the channels is [`CHANNELS.md`](CHANNELS.md).@@ -71,7 +74,12 @@ internal traceability tag.shipped as a beta at least 3 days earlier unless a written justificationis provided- tags point at the original source commit, not a generated release commit-- stable notes are always `releases/vYYYY.MDD.P.md`+- stable notes are always `releases/vYYYY.MDD.P.md` in the end state: a+ promoted beta's notes are drafted and edited at+ `releases/beta/v<beta-version>.md` on `master` during the soak (the+ promoted commit cannot carry a file named for a promotion date that was+ unknown when it was created), and a post-stable canonicalization PR+ moves them to the versioned name- canaries, nightlies, and betas never create GitHub Releases- canaries, nightlies, and betas never require changelog generation- Docker `:latest` moves only on stable releases; master builds publish@@ -157,6 +165,13 @@ Betas are manual promotions. Dispatchdispatched at that tag to publish the `:beta` images- after publishing, the release smoke suite runs against the exact publishedbeta version as verification+- a `draft_stable_notes` job also generates the eventual stable's notes+ skeleton — `releases/beta/v<beta-version>.md`, grouped from+ `git log <last-stable-tag>..<source-commit>` — and force-pushes it to the+ machine-owned `release-notes/v<beta-version>` branch. Open the PR from+ the job-summary link (a human opens it so CI runs) and edit the notes+ during the soak; the stable promotion reads the merged file from+ `master`- `dry_run: true` previews the publish and skips the tag push, Dockerdispatch, and post-publish smoke@@ -228,7 +243,11 @@ Before running stable:1. pick the beta you are promoting (its source commit is the `source_ref`)2. confirm the beta has soaked for 3 days with no open blockers3. resolve the target stable version with `./scripts/release.sh stable --date "$(date +%F)" --print-version`-4. create or update `releases/vYYYY.MDD.P.md` on that source ref+4. make sure the notes PR from the beta's draft branch+ (`release-notes/v<beta-version>`, adding+ `releases/beta/v<beta-version>.md`) is merged on `master` — or, for+ candidate builds, that the candidate branch itself carries+ `releases/vYYYY.MDD.P.md`5. run the stable workflow from that source refExample:@@ -241,11 +260,19 @@ The workflow:- re-verifies the exact source ref- computes the next stable patch slot for the chosen UTC date+- resolves the release notes in preflight: `releases/vYYYY.MDD.P.md` at+ the source commit (the candidate fix path) takes precedence, otherwise+ `releases/beta/v<beta-version>.md` on `master` (a promoted beta). When+ neither exists the run fails before the `npm-stable` approval gate with+ the missing path named- publishes `YYYY.MDD.P` under npm dist-tag `latest`- creates git tag `vYYYY.MDD.P`- dispatches [`docker.yml`](../.github/workflows/docker.yml) at that tag topublish `:latest` and the versioned stable images-- creates or updates the GitHub Release from `releases/vYYYY.MDD.P.md`+- creates or updates the GitHub Release from the resolved notes file+- for master-side beta notes, pushes a `release-notes/v<version>-canonicalize`+ branch that `git mv`s them to `releases/vYYYY.MDD.P.md` — open and merge+ its PR to restore the canonical layout## Docker Image Tags@@ -314,6 +341,12 @@ Stable changelog files live at:Canaries do not get changelog files.+The `draft_stable_notes` job seeds a deterministic skeleton (grouped+commit subjects) on the `release-notes/v<beta-version>` branch at beta+publish; the flows below turn that skeleton into narrative release notes+during the soak. Run them against the draft branch's+`releases/beta/v<beta-version>.md` and push to the notes PR.+Recommended local generation flow:```bashdiff --git a/scripts/create-github-release.sh b/scripts/create-github-release.shindex f326811a57..603f5832fd 100755--- a/scripts/create-github-release.sh+++ b/scripts/create-github-release.sh@@ -7,15 +7,17 @@ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"dry_run=falseversion=""+notes_file_override=""usage() {cat <<'EOF'Usage:- ./scripts/create-github-release.sh <version> [--dry-run]+ ./scripts/create-github-release.sh <version> [--dry-run] [--notes-file PATH]Examples:./scripts/create-github-release.sh 2026.318.0./scripts/create-github-release.sh 2026.318.0 --dry-run+ ./scripts/create-github-release.sh 2026.318.0 --notes-file /tmp/stable-notes.mdNotes:- Run this after pushing the stable tag.@@ -28,6 +30,14 @@ EOFwhile [ $# -gt 0 ]; docase "$1" in--dry-run) dry_run=true ;;+ --notes-file)+ shift+ if [ $# -eq 0 ]; then+ echo "Error: --notes-file requires a path." >&2+ exit 1+ fi+ notes_file_override="$1"+ ;;-h|--help)usageexit 0@@ -55,6 +65,9 @@ fitag="v$version"notes_file="$REPO_ROOT/releases/${tag}.md"+if [ -n "$notes_file_override" ]; then+ notes_file="$notes_file_override"+fiif [ "${GITHUB_ACTIONS:-}" = "true" ] && [ -z "${PUBLISH_REMOTE:-}" ] && git_remote_exists origin; thenPUBLISH_REMOTE=originfidiff --git a/scripts/draft-stable-notes.sh b/scripts/draft-stable-notes.shnew file mode 100755index 0000000000..1ba75033d7--- /dev/null+++ b/scripts/draft-stable-notes.sh@@ -0,0 +1,129 @@+#!/usr/bin/env bash+set -euo pipefail++REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"+# shellcheck source=./release-lib.sh+. "$REPO_ROOT/scripts/release-lib.sh"++beta_version=""+out_file=""+repo_dir="$REPO_ROOT"++usage() {+ cat <<'EOF'+Usage:+ ./scripts/draft-stable-notes.sh <beta-version> [--out PATH] [--repo-dir PATH]++Examples:+ ./scripts/draft-stable-notes.sh 2026.817.1-beta.0+ ./scripts/draft-stable-notes.sh 2026.817.1-beta.0 --out /tmp/draft.md++Notes:+ - Generates a stable release-notes draft for the given published beta:+ the commit range from the newest stable tag (v*) to the beta's source+ commit, grouped by conventional-commit type.+ - Written to releases/beta/v<beta-version>.md by default. The draft is+ meant to be committed to master via PR and edited during the beta+ soak; the stable promotion reads it from master.+ - With no stable tag yet, the range falls back to the previous beta+ tag, and failing that to the full history of the source commit.+EOF+}++while [ $# -gt 0 ]; do+ case "$1" in+ --out)+ shift+ [ $# -gt 0 ] || release_fail "--out requires a path."+ out_file="$1"+ ;;+ --repo-dir)+ shift+ [ $# -gt 0 ] || release_fail "--repo-dir requires a path."+ repo_dir="$1"+ ;;+ -h|--help)+ usage+ exit 0+ ;;+ *)+ if [ -n "$beta_version" ]; then+ release_fail "only one beta version may be provided."+ fi+ beta_version="$1"+ ;;+ esac+ shift+done++if [ -z "$beta_version" ]; then+ usage+ exit 1+fi++if [[ ! "$beta_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$ ]]; then+ release_fail "beta version must look like 2026.318.1-beta.0, got: $beta_version"+fi++beta_tag="beta/v${beta_version}"+if ! git -C "$repo_dir" rev-parse --verify "refs/tags/${beta_tag}" >/dev/null 2>&1; then+ release_fail "beta tag ${beta_tag} does not exist. Draft notes are generated from a published beta."+fi+source_sha="$(git -C "$repo_dir" rev-parse "${beta_tag}^{commit}")"++if [ -z "$out_file" ]; then+ out_file="${repo_dir}/releases/beta/v${beta_version}.md"+fi++# Range start: the newest stable tag reachable from the source commit —+# not the newest by version, which can sit on a divergent lineage (a+# stable cut from a candidate branch, or a source that predates it) and+# would produce an empty or wrong range. Before the first reachable+# stable, fall back to the nearest beta tag strictly before the source;+# with no marker at all, cover the source commit's full history.+range_start="$(git -C "$repo_dir" describe --tags --match 'v[0-9]*' --abbrev=0 "$source_sha" 2>/dev/null || true)"+range_label="$range_start"+if [ -z "$range_start" ]; then+ range_start="$(git -C "$repo_dir" describe --tags --match 'beta/v*' --abbrev=0 "${source_sha}^" 2>/dev/null || true)"+ range_label="$range_start"+fi+if [ -n "$range_start" ]; then+ range="${range_start}..${source_sha}"+else+ range="$source_sha"+ range_label="the beginning of history"+ release_info "No stable or prior beta tag found; drafting from full history."+fi++subjects="$(git -C "$repo_dir" log --no-merges --format='%s' "$range")"++section() {+ local title="$1" pattern="$2" invert="${3:-false}" body+ if [ "$invert" = true ]; then+ body="$(printf '%s\n' "$subjects" | grep -Ev "$pattern" || true)"+ else+ body="$(printf '%s\n' "$subjects" | grep -E "$pattern" || true)"+ fi+ [ -n "$body" ] || return 0+ printf '## %s\n\n' "$title"+ printf '%s\n' "$body" | sed 's/^/- /'+ printf '\n'+}++conventional='^(feat|fix)(\([^)]*\))?!?: '+mkdir -p "$(dirname "$out_file")"+{+ printf '# Paperclip stable draft — from beta %s\n\n' "$beta_version"+ printf '> Auto-generated at beta publish from `git log %s..%s`.\n' "${range_label}" "${source_sha:0:9}"+ printf '> Edit freely during the soak: rewrite for release-notes voice,\n'+ printf '> fold noise, and call out anything a self-hoster must act on.\n'+ printf '> The stable promotion reads this file from master and publishes\n'+ printf '> it as the GitHub Release body under the stable version.\n\n'+ section 'Features' '^feat(\([^)]*\))?!?: '+ section 'Fixes' '^fix(\([^)]*\))?!?: '+ section 'Other changes' "$conventional" true+} > "$out_file"++release_info "Draft stable notes written to $out_file"+release_info " Source beta: $beta_version ($source_sha)"+release_info " Range start: $range_label"diff --git a/scripts/draft-stable-notes.test.mjs b/scripts/draft-stable-notes.test.mjsnew file mode 100644index 0000000000..c5bb01dfc0--- /dev/null+++ b/scripts/draft-stable-notes.test.mjs@@ -0,0 +1,139 @@+import assert from "node:assert/strict";+import { execFileSync } from "node:child_process";+import { mkdtempSync, readFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import test from "node:test";++const repoRoot = new URL("..", import.meta.url).pathname.replace(/\/$/, "");+const script = join(repoRoot, "scripts", "draft-stable-notes.sh");++function git(dir, ...args) {+ return execFileSync("git", ["-C", dir, ...args], {+ encoding: "utf8",+ env: {+ ...process.env,+ GIT_AUTHOR_NAME: "t",+ GIT_AUTHOR_EMAIL: "[email protected]",+ GIT_COMMITTER_NAME: "t",+ GIT_COMMITTER_EMAIL: "[email protected]",+ },+ });+}++function commit(dir, subject) {+ git(dir, "commit", "--allow-empty", "-m", subject);+}++function makeFixtureRepo() {+ const dir = mkdtempSync(join(tmpdir(), "draft-stable-notes-"));+ git(dir, "init", "-q", "-b", "master");+ return dir;+}++function runDraft(dir, betaVersion, extraArgs = []) {+ const out = join(dir, "draft.md");+ const stdout = execFileSync(+ "bash",+ [script, betaVersion, "--repo-dir", dir, "--out", out, ...extraArgs],+ { encoding: "utf8" }+ );+ return { stdout, body: readFileSync(out, "utf8") };+}++test("drafts grouped notes from the newest stable tag to the beta source", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: ancient work (#1)");+ git(dir, "tag", "v2026.100.0");+ commit(dir, "feat: add widgets (#2)");+ commit(dir, "fix(ui): unbreak widget list (#3)");+ commit(dir, "chore: bump deps (#4)");+ commit(dir, "feat(api)!: breaking widget API (#5)");+ git(dir, "tag", "beta/v2026.101.0-beta.0");++ const { body } = runDraft(dir, "2026.101.0-beta.0");++ assert.match(body, /^# Paperclip stable draft — from beta 2026\.101\.0-beta\.0/);+ assert.match(body, /## Features\n\n- feat\(api\)!: breaking widget API \(#5\)\n- feat: add widgets \(#2\)/);+ assert.match(body, /## Fixes\n\n- fix\(ui\): unbreak widget list \(#3\)/);+ assert.match(body, /## Other changes\n\n- chore: bump deps \(#4\)/);+ assert.doesNotMatch(body, /ancient work/);+});++test("uses the nearest ancestor stable tag, not the newest by version", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: old work (#1)");+ git(dir, "tag", "v2026.100.0");+ commit(dir, "feat: mid work (#2)");+ git(dir, "tag", "beta/v2026.150.0-beta.0");+ commit(dir, "feat: new work (#3)");+ git(dir, "tag", "v2026.200.0");++ // Promoting the older source must draft against its own lineage's last+ // stable (v2026.100.0), not the newer v2026.200.0 that already contains+ // it — that range would be empty.+ const { body } = runDraft(dir, "2026.150.0-beta.0");++ assert.match(body, /- feat: mid work \(#2\)/);+ assert.doesNotMatch(body, /old work/);+ assert.doesNotMatch(body, /new work/);+});++test("falls back to the previous beta tag when no stable tag exists", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: first-train work (#1)");+ git(dir, "tag", "beta/v2026.100.0-beta.0");+ commit(dir, "fix: second-train fix (#2)");+ git(dir, "tag", "beta/v2026.101.0-beta.0");++ const { body } = runDraft(dir, "2026.101.0-beta.0");++ assert.match(body, /- fix: second-train fix \(#2\)/);+ assert.doesNotMatch(body, /first-train work/);+});++test("covers full history when no earlier marker exists", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: the very first commit (#1)");+ git(dir, "tag", "beta/v2026.100.0-beta.0");++ const { body } = runDraft(dir, "2026.100.0-beta.0");++ assert.match(body, /- feat: the very first commit \(#1\)/);+});++test("writes to releases/beta/v<version>.md inside the repo by default", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: default path (#1)");+ git(dir, "tag", "beta/v2026.100.0-beta.0");++ execFileSync("bash", [script, "2026.100.0-beta.0", "--repo-dir", dir], {+ encoding: "utf8",+ });+ const body = readFileSync(+ join(dir, "releases", "beta", "v2026.100.0-beta.0.md"),+ "utf8"+ );+ assert.match(body, /- feat: default path \(#1\)/);+});++test("rejects a malformed beta version", () => {+ const dir = makeFixtureRepo();+ assert.throws(() =>+ execFileSync("bash", [script, "2026.100.0", "--repo-dir", dir], {+ encoding: "utf8",+ stdio: "pipe",+ })+ );+});++test("rejects a beta version whose tag does not exist", () => {+ const dir = makeFixtureRepo();+ commit(dir, "feat: unrelated (#1)");+ assert.throws(() =>+ execFileSync("bash", [script, "2026.100.0-beta.9", "--repo-dir", dir], {+ encoding: "utf8",+ stdio: "pipe",+ })+ );+});diff --git a/scripts/release.sh b/scripts/release.shindex 5d51aab69a..9c94f467e6 100755--- a/scripts/release.sh+++ b/scripts/release.sh@@ -12,6 +12,7 @@ dry_run=falseskip_verify=falseprint_version_only=falsefrom_candidate=false+notes_file_override=tag_name=""cleanup_on_exit=false@@ -19,7 +20,7 @@ cleanup_on_exit=falseusage() {cat <<'EOF'Usage:- ./scripts/release.sh <canary|nightly|beta|stable> [--date YYYY-MM-DD] [--dry-run] [--skip-verify] [--print-version]+ ./scripts/release.sh <canary|nightly|beta|stable> [--date YYYY-MM-DD] [--dry-run] [--skip-verify] [--print-version] [--notes-file PATH]Examples:./scripts/release.sh canary@@ -48,7 +49,10 @@ Notes:validating the candidate branch before using it.- Stable releases publish YYYY.MDD.P under the npm dist-tag "latest" andcreate the git tag vYYYY.MDD.P.- - Non-dry-run stable release notes must already exist at releases/vYYYY.MDD.P.md.+ - Non-dry-run stable release notes must already exist at releases/vYYYY.MDD.P.md,+ or be supplied explicitly with --notes-file (stable only). The override+ exists so promotions can read notes maintained on master instead of+ requiring them inside the promoted source commit's tree.- The script rewrites versions temporarily and restores the working tree onexit. Tags always point at the original source commit, not a generatedrelease commit.@@ -114,6 +118,11 @@ while [ $# -gt 0 ]; do--skip-verify) skip_verify=true ;;--print-version) print_version_only=true ;;--from-candidate) from_candidate=true ;;+ --notes-file)+ shift+ [ $# -gt 0 ] || release_fail "--notes-file requires a path."+ notes_file_override="$1"+ ;;-h|--help)usageexit 0@@ -134,6 +143,10 @@ if [ "$from_candidate" = true ] && [ "$channel" != "beta" ]; thenrelease_fail "--from-candidate only applies to the beta channel."fi+if [ -n "$notes_file_override" ] && [ "$channel" != "stable" ]; then+ release_fail "--notes-file only applies to the stable channel."+fi+PUBLISH_REMOTE="$(resolve_release_remote)"fetch_release_remote "$PUBLISH_REMOTE"@@ -203,6 +216,9 @@ if [ "$print_version_only" = true ]; thenfiNOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"+if [ -n "$notes_file_override" ]; then+ NOTES_FILE="$notes_file_override"+firequire_clean_worktreerequire_npm_publish_auth "$dry_run"