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.

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

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

<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. Use a single commit whose message ends with [skip ci] so merging the change does not trigger a dotcom deploy or other push- and pull_request-triggered workflows (release-notes edits are docs-only):

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 [skip ci]"
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.
• 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]: pushing to production (and the hotfixes → production promotion) triggers deploy-dotcom.yml. A merge commit containing [skip ci] is skipped by GitHub Actions entirely, so the release-notes change can land on production — ready to ride the next SDK release, which pushes the production ref to docs-production — without deploying tldraw.com.

[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 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.
2. Publish the release to NPM — this happens outside of this skill. publish-new.ts publishes the draft release created in step 1.
3. Second run — now that the release is published, the status script will detect needs_archive: true. 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

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