/update-release-notes

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:

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:

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:

<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:

<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:

<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:

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):

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:

<skill-d