home / skills / tldraw / tldraw / update-release-notes

update-release-notes skill

safe

This skill updates the release notes by adding new PR entries to next.mdx and archiving when a new version is published.

npx playbooks add skill tldraw/tldraw --skill update-release-notes

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.7 KB

---
name: update-release-notes
description: Update the release notes file at `apps/docs/content/releases/next.mdx` based on PRs merged to main 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: adding new PR entries to `next.mdx` and archiving releases when a new version is published.

## Process

### 1. Check status

Run the status script to determine versions and diff branch:

```bash
.claude/skills/update-release-notes/scripts/get-changelog-status.sh
```

This returns:

- `diff_branch` (e.g., `v4.3.x`) - the branch to diff against
- `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. 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

Get PR numbers merged since the release branch:

```bash
.claude/skills/update-release-notes/scripts/get-new-prs.sh <diff_branch>
```

### 4. Fetch PR details

Batch fetch all PR information:

```bash
.claude/skills/update-release-notes/scripts/fetch-pr-batch.sh <pr1> <pr2> ...
```

### 5. Update next.mdx

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

### 6. Verify

Check that:

- PR links are correct
- Community contributors are credited
- Sections are in the correct order
- Breaking changes are marked with 💥

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

## References

- **Style guide**: See `../shared/release-notes-guide.md` for guidance on what a release notes article should contain and how to format it.
- **Scripts**: See `scripts/` for automation helpers

Overview

This skill automates updating and archiving release notes in apps/docs/content/releases/next.mdx. It detects merged PRs since the last published release, adds curated entries to the next.mdx file, and archives next.mdx to a versioned file when a new release is published. The goal is consistent, accurate release notes with minimal manual work.

How this skill works

The skill first runs a status script to determine the diff branch, latest published release, and whether archival is required. If a new version was published, it copies next.mdx to a versioned file, updates frontmatter and links, and resets next.mdx for new entries. It then gathers PR numbers merged since the diff branch, batch-fetches PR details, filters and categorizes PRs per the style guide, and inserts validated entries into the appropriate sections of next.mdx.

When to use it

After merging a set of PRs to main and you want the next.mdx file updated with new entries.
When a new release is published and you need to archive next.mdx into a versioned release file.
Before publishing a release to ensure release notes reflect all merged changes since the last release.
When you need to enforce consistent release-note formatting and contributor attribution.

Best practices

Run the provided status script first to identify diff_branch and whether archival is needed.
Follow the shared release-notes style guide for PR labels and body format to ensure automatic categorization.
Skip or mark PRs that should be omitted (internal changes or trivial fixes) according to the guide.
Verify reverts and dependent bug-fix PRs are handled: remove reverted entries and skip fixes caused in the same cycle.
Review the generated next.mdx for correct section order, community credits, and 💥 marking for breaking changes.

Example use cases

Automating release-note updates after a sprint where numerous feature and bugfix PRs landed on main.
Archiving next.mdx to vX.Y.0.mdx automatically when a release pipeline publishes a new version.
Maintaining consistent contributor credit and PR links across releases without manual edits.
Filtering out noisy or irrelevant PRs from release notes while promoting notable changes to featured sections.

FAQ

How does the skill decide which PRs to include?

It uses PR labels and body text compared against the release-notes style guide, skips PRs flagged for omission, filters bug-fixes caused in the same cycle, and treats reverts specially by removing original entries.

What triggers archiving of next.mdx?

Archival happens when the status script detects a published release newer than the next.mdx last_version field; the file is copied to a versioned .mdx, frontmatter updated, and next.mdx is reset.