Skip to content

The open-source app everyone uses to manage agents at work

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.md
index 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 into
a 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 a
Discord announcement, or has a `discord_announcement` document that needs to
be refreshed for a new date/version.
@@ -123,6 +128,12 @@ Notes on the template:
- The opening and closing `:paperclip: :paperclip: :paperclip:` bookends are
part 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 style
and 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 the
release 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 (see
diff --git a/.agents/skills/release-changelog/SKILL.md b/.agents/skills/release-changelog/SKILL.md
index 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:
```bash
git 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-merges
ls .changeset/*.md | grep -v README.md
gh 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 and
the `v` on the version.
@@ -177,7 +232,7 @@ The `Contributors` section should always be included. List every person who auth
commits in the release range, @-mentioning them by their **GitHub username** (not their
real 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.yml
index 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: read
outputs:
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 repository
uses: actions/checkout@v7
@@ -724,6 +790,7 @@ jobs:
fi
beta_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: write
id-token: write
actions: 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 stable
env:
GITHUB_ACTIONS: "true"
@@ -844,6 +981,9 @@ jobs:
if [ -n "${{ inputs.stable_date }}" ]; then
args+=(--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: tag
run: |
tag="$(git tag --points-at HEAD | grep '^v' | head -1)"
if [ -z "$tag" ]; then
echo "Error: no stable tag points at HEAD after release." >&2
exit 1
fi
+ echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
if ! git push origin "refs/tags/${tag}"; then
sha="$(git rev-parse HEAD)"
{
@@ -913,4 +1055,59 @@ jobs:
echo "Error: no v* tag points at HEAD after stable release." >&2
exit 1
fi
- ./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.md
index 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 shows
the 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 a
real 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; the
soak 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 run
diff --git a/doc/RELEASING.md b/doc/RELEASING.md
index 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 justification
is 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. Dispatch
dispatched at that tag to publish the `:beta` images
- after publishing, the release smoke suite runs against the exact published
beta 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, Docker
dispatch, 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 blockers
3. 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 ref
Example:
@@ -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 to
publish `: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:
```bash
diff --git a/scripts/create-github-release.sh b/scripts/create-github-release.sh
index 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=false
version=""
+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.md
Notes:
- Run this after pushing the stable tag.
@@ -28,6 +30,14 @@ EOF
while [ $# -gt 0 ]; do
case "$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)
usage
exit 0
@@ -55,6 +65,9 @@ fi
tag="v$version"
notes_file="$REPO_ROOT/releases/${tag}.md"
+if [ -n "$notes_file_override" ]; then
+ notes_file="$notes_file_override"
+fi
if [ "${GITHUB_ACTIONS:-}" = "true" ] && [ -z "${PUBLISH_REMOTE:-}" ] && git_remote_exists origin; then
PUBLISH_REMOTE=origin
fi
diff --git a/scripts/draft-stable-notes.sh b/scripts/draft-stable-notes.sh
new file mode 100755
index 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.mjs
new file mode 100644
index 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.sh
index 5d51aab69a..9c94f467e6 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -12,6 +12,7 @@ dry_run=false
skip_verify=false
print_version_only=false
from_candidate=false
+notes_file_override=
tag_name=""
cleanup_on_exit=false
@@ -19,7 +20,7 @@ cleanup_on_exit=false
usage() {
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" and
create 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 on
exit. Tags always point at the original source commit, not a generated
release 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)
usage
exit 0
@@ -134,6 +143,10 @@ if [ "$from_candidate" = true ] && [ "$channel" != "beta" ]; then
release_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 ]; then
fi
NOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"
+if [ -n "$notes_file_override" ]; then
+ NOTES_FILE="$notes_file_override"
+fi
require_clean_worktree
require_npm_publish_auth "$dry_run"