upstream-tldraw/skills/update-release-notes/SKILL.md

---
name: update-release-notes
description: Update the release notes file at `apps/docs/content/releases/next.mdx` in the tldraw/tldraw repo based on PRs since the previous release, or archive `next.mdx` to a versioned file when a new version is published.
allowed-tools: Bash(git:*), Bash(gh:*)
---

# Update release notes

This skill handles the operational tasks of maintaining release notes in the **tldraw/tldraw** repo: adding new PR entries to `next.mdx` and archiving releases when a new version is published.

This skill runs from the tldraw-internal repo but operates on a local clone of tldraw/tldraw.

## Setup

Before starting, clone the tldraw repo:

```bash
git clone https://github.com/tldraw/tldraw.git /tmp/tldraw
```

All scripts take the repo path as their first argument. Run script commands from the repository root by replacing `<skill-dir>` with the directory that contains this `SKILL.md`. All file edits happen in this clone. At the end, commit and push from the clone.

## Release cycle

The SDK releases every four weeks. One week before launch, the SDK is frozen and a `production` branch is cut from `main`. During release week, only hotfixes are cherry-picked to `production`.

The release notes in `next.mdx` must ultimately reflect what ships on the `production` branch. However, during the ~3 development weeks before the freeze, we build up release notes from `main` so they're not empty. The status script detects which phase we're in based on the date of the last minor release:

- **Development weeks** (`source: "main"`, <3 weeks since last minor release): PRs are gathered from `main` since the last release tag. These are preliminary — some may not ship if they're reverted or if production cherry-picks differ.
- **Freeze week** (`source: "production"`, 3+ weeks since last minor release): PRs are gathered from the `production` branch using `git cherry` against the previous release branch. Only PRs that landed before the freeze or were hotfixed onto production are included. Entries accumulated from `main` that aren't on production will be pruned.

`next.mdx` itself also has to be **on `production`** before the release is published, not just describe it. `prepack.ts` generates the `RELEASE_NOTES.md` that ships inside the `tldraw` npm package from the checkout being published, using `next.mdx` as the entry for the version being released. `production` only moves by hotfix during the freeze, so a release-notes PR merged to `main` reaches it only if it also carries the `dotcom-hotfix-please` label (see step 10). The check before publishing is an empty diff:

```bash
git diff --stat origin/production origin/main -- apps/docs/content/releases/next.mdx
```

## Process

### 1. Check status

Run the status script to determine versions and diff branch:

```bash
<skill-dir>/scripts/get-changelog-status.sh /tmp/tldraw
```

This returns:

- `source` - either `"main"` (development weeks) or `"production"` (release week)
- `diff_branch` (e.g., `v4.3.x`) - the branch to diff against (used when `source` is `"production"`)
- `last_tag` (e.g., `v4.4.0`) - the last release tag (used when `source` is `"main"`)
- `latest_release` - the most recent published release
- Whether archival is needed

### 2. Handle archival (if needed)

If a new release was published since `last_version` in `next.mdx`:

1. Copy `next.mdx` content to `vX.Y.0.mdx` (e.g., `v4.3.0.mdx`)
2. Update the frontmatter in the new file:
   - Set `title` to the version
   - Update dates
   - Add the GitHub release link after frontmatter
3. Add the new version to the releases index at `apps/docs/content/getting-started/releases.mdx`:
   - Add a line at the top of the appropriate `## v{major}.x` section
   - Format: `- [vX.Y](/releases/vX.Y.0) - Brief description`
   - The description should be a short summary of the release highlights from the intro paragraph (3-5 key features, comma-separated)
   - If a new major version section is needed, create it above the previous one
4. Reset `next.mdx`:
   - Update `last_version` field to the new release
   - Clear the content sections
   - Keep the file structure for accumulating new changes

### 3. Find new PRs

The approach depends on the `source` field from step 1.

**If `source` is `"production"` (release week):**

Get PR numbers on the production branch since the previous release:

```bash
<skill-dir>/scripts/get-new-prs.sh /tmp/tldraw <diff_branch>
```

This uses `git cherry` (same approach as `extract-draft-changelog.tsx`) to compare patches between `origin/production` and `origin/<diff_branch>`. Unlike `git log`, `git cherry` correctly handles cherry-picked hotfix commits by comparing patch content rather than commit hashes.

**If `source` is `"main"` (development weeks):**

Get PR numbers on main since the last release tag:

```bash
<skill-dir>/scripts/get-new-prs-from-main.sh /tmp/tldraw <last_tag>
```

This uses `git cherry` to compare patches between `origin/main` and the release tag, excluding commits that were cherry-picked to production and already shipped in the release.

**Both scripts output:**

- **stdout**: PR numbers (one per line) extracted from commit messages
- **stderr**: Commits without PR numbers (typically hotfixes or direct commits)

### 4. Resolve hotfix commits

Check stderr from step 3 for any `[HOTFIX]` commits without PR numbers. For each SDK-relevant one (skip dotcom-only), find the corresponding PR:

```bash
gh pr list -R tldraw/tldraw --state merged --search "<hotfix title keywords>" --json number,title --jq '.[]'
```

Also check `sdk-hotfix-please` labeled PRs, but verify they actually landed on production — this label is also used for patch releases on the previous release branch (e.g., v4.3.x):

```bash
gh pr list -R tldraw/tldraw --label "sdk-hotfix-please" --state merged --limit 20 --json number,title,mergedAt
```

Add any matched PR numbers to the production PR list from step 3.

### 5. Fetch PR details

Batch fetch all PR information:

```bash
<skill-dir>/scripts/fetch-pr-batch.sh <pr1> <pr2> ...
```

### 6. Remove stale entries

Compare the full PR list (from steps 3 + 4) against the PR numbers already referenced in `next.mdx`. Remove any entries from `next.mdx` whose PRs are **not** in the current set.

- **When `source` is `"production"`**: This prunes entries that were accumulated from `main` during development but didn't make it to production. These are PRs that landed on `main` after the production branch was cut and will not ship in this release.
- **When `source` is `"main"`**: This removes entries for PRs that were reverted or otherwise no longer on main. Pruning is less aggressive since the full set isn't finalized until production is cut.

When removing an entry, also check whether it was referenced in a featured "What's new" section and remove that section too. Update the intro paragraph if it mentions a removed feature.

### 7. Add new entries

For each PR not already in `next.mdx`:

1. Check PR labels and body against the style guide's categorization rules
2. Skip PRs that should be omitted (see style guide)
3. Skip PRs that fix bugs introduced in the same release cycle (i.e., bugs caused by other PRs already in `next.mdx` that were not in the previous release)
4. If a PR is a revert, also remove the original reverted PR's entry from `next.mdx` if present
5. Add entries to the appropriate section
6. Promote significant changes to featured sections when warranted

### 8. Verify

Check that:

- Every PR referenced in `next.mdx` is in the current PR set (from `main` or `production` depending on `source`)
- PR links are correct
- Community contributors are credited
- Sections are in the correct order
- Breaking changes are marked with 💥
- Deprecations are marked with 🔜

**Note**: When `source` is `"main"`, the entries are preliminary. Some may be pruned later when the production branch is cut and the source switches to `"production"`.

### 9. Update the draft GitHub release

Keep the draft GitHub release for the next minor in sync with `next.mdx`. `publish-new.ts` finds the draft by name (`vX.Y.0`) and publishes its body verbatim at release time, so mirroring `next.mdx` here means the GitHub release and the docs release page always match.

```bash
<skill-dir>/scripts/update-draft-release.sh /tmp/tldraw
```

This script:

- Derives the target version from `last_version` in `next.mdx` (bump minor, patch `0` — e.g. `v5.2.0` → `v5.3.0`).
- Uses the `next.mdx` body (frontmatter stripped) as the release body.
- Creates the draft if none exists, or edits the existing draft named `vX.Y.0`. It refuses to touch an already-published release, and refuses to write an empty body.

**Major releases / version overrides:** the minor bump above is the default because nearly every release is a minor. `publish-new.ts` looks up the draft by the version it resolves — for `--bump major` (or an override) that comes from NPM, not a minor bump, so a hardcoded minor would leave the draft misnamed and `getDraftRelease` would fail. When the next release is a major or otherwise not the next minor, pass the target explicitly so the draft name matches:

```bash
<skill-dir>/scripts/update-draft-release.sh /tmp/tldraw v6.0.0
```

Run this after every `next.mdx` update, including the release-week runs. On the second (post-publish) run the previous minor's draft has already been published, so this creates a fresh draft for the new next minor derived from the reset `last_version`.

### 10. Push changes

After editing `next.mdx` (and any archive files), commit and push from the tldraw clone. Do not add `[skip ci]` to the branch commit: required pull request checks will never start when the marker is present. The PR title below adds the marker to the eventual squash-merge commit instead.

```bash
cd /tmp/tldraw
BRANCH="update-release-notes-$(date -u +%Y%m%d-%H%M)"
git checkout -b "$BRANCH"
git add apps/docs/content/releases/
git commit -m "docs(releases): update release notes"
git push -u origin "$BRANCH"
```

Then create the PR using the `../pr/SKILL.md` workflow and the standards in `../write-pr/SKILL.md`:

- **Label**: add `docs-hotfix-please` (`gh pr edit <number> --add-label docs-hotfix-please`, or `--label docs-hotfix-please` on `gh pr create`). Without it, merging to `main` never cherry-picks the notes onto the current release branch (`vX.Y.x`), so the update never reaches tldraw.dev — which is the whole point of the run.
- **Freeze-week label**: when `source` is `"production"`, also add `dotcom-hotfix-please`. That cherry-picks the merged PR onto `hotfixes` and from there onto `production`, which is where `prepack.ts` reads `next.mdx` from when the release is published (see "Release cycle"). `docs-hotfix-please` alone never touches `production`. After the merge, confirm the hotfix landed with the diff command from "Release cycle"; if the dotcom hotfix bot fails, cherry-pick the squash commit onto a branch from `hotfixes` by hand, strip any `[skip ci]` marker from the commit message, and open a `[HOTFIX]` PR against `hotfixes`.
- **Title**: `docs(releases): update release notes [skip ci]` — the `[skip ci]` must be in the PR title because GitHub's squash-merge uses the PR title as the merge commit subject, and that merge commit is what needs to skip CI. **Squash-merge** the PR (do not rebase- or create-a-merge-commit) so exactly one `[skip ci]` commit lands on the base branch.
- **Change type**: `other`
- **Test plan**: Remove the numbered list (no manual testing steps). Untick both unit tests and end to end tests.
- **Release notes**: Omit this section (internal docs work with no user-facing impact)
- **Description paragraph**: Start with "In order to..." and mention the source (`main` or `production`) and what was updated (new entries added, stale entries pruned, archival performed, draft GitHub release synced, etc.)
- Include a **Code changes** table with a `Documentation` row

**Why `[skip ci]` is only in the PR title**: branch commits need to run the required pull request checks. GitHub's squash merge uses the PR title for the merge commit, so the marker skips push workflows when the notes-only change lands on `main`.

`[skip ci]` does not interfere with the `docs-hotfix-please` label: `trigger-sdk-hotfix.yml` runs on `pull_request_target`, which GitHub's skip-ci markers do not affect, and the hotfix script strips skip-ci markers from the cherry-picked commit so the release-branch push still triggers the publish workflow. The trigger fires when a labeled PR is merged; to re-trigger it later, remove and re-add the label on the merged PR. The same applies to `dotcom-hotfix-please` once #10629 is fixed; until then its bot keeps the marker and the hotfix PR it opens never gets its checks.

Never write the literal `[skip ci]` string anywhere else in a PR body. GitHub reads the marker from the whole squash-merge commit message, and the PR body becomes that commit's body.

## The `last_version` field

The `next.mdx` frontmatter includes a `last_version` field that tracks the most recent published release. This determines which PRs are "new" and need to be added.

## SDK release workflow

During an SDK release, this skill is run **twice** to get the docs site into its post-release state:

1. **First run** — update `next.mdx` with all PRs that will ship in the release (source is `"production"` during freeze week). This ensures the release notes are complete before publishing. The draft-release step (step 9) syncs the draft `vX.Y.0` GitHub release from this `next.mdx`, so `publish-new.ts` has the finished notes ready to publish. The PR carries both `docs-hotfix-please` and `dotcom-hotfix-please` (step 10) so the file reaches `v(X.Y-1).x` for the site and `production` for the package.
2. **Gate** — before anyone publishes, `next.mdx` must be identical on `production` and `main` (the diff command in "Release cycle" prints nothing), and the draft `vX.Y.0` release must match `next.mdx`. If a later edit to `next.mdx` landed on `main` without the dotcom hotfix, or after the last draft sync, fix that first.
3. **Publish the release to NPM** — this happens outside of this skill. `publish-new.ts` publishes the draft release created in step 1, and `prepack.ts` bakes `production`'s `next.mdx` into the `tldraw` package as that version's `RELEASE_NOTES.md` entry. The publish pushes the version bump to `main`, not `production`.
4. **Second run** — now that the release is published, the status script will detect `needs_archive: true`. This workflow runs on `production` pushes, and the publish doesn't make one, so the second run happens on the next `production` push (normally the post-launch dotcom release from `main`), or when someone dispatches `update-release-notes.yml` by hand. This run:
   - Archives `next.mdx` to a versioned file (e.g., `v4.5.0.mdx`)
   - Adds the new version to the releases index (`releases.mdx`)
   - Resets `next.mdx` with the new `last_version`
   - Finds PRs that landed on `main` during the freeze (since the release tag) and adds them to the fresh `next.mdx`
   - Syncs a fresh draft for the new next minor (step 9), since the previous draft is now published
   - Needs `docs-hotfix-please` (not `dotcom-hotfix-please`: `production` no longer matters for the notes once the package is out) so it lands on the new `vX.Y.x` branch and republishes the site

After the second run, the docs site reflects the published release and `next.mdx` already has a head start on the next cycle's changes.

## References

- **Style guide**: See `../shared/release-notes-guide.md` for guidance on what a release notes article should contain and how to format it.
- **Writing guide**: See `../../VOICE.md` for voice and style conventions.
- **Scripts**: See `scripts/` for automation helpers, including `update-draft-release.sh` for syncing the draft GitHub release