Skip to content

Commit 9204c4b

Browse files
authored
chore(skills): add releases index update and SDK release workflow to update-release-notes skill (tldraw#8281)
In order to automate the full SDK release docs workflow, this PR updates the `update-release-notes` skill with two additions: 1. **Releases index update during archival** — when archiving `next.mdx` to a versioned file, the skill now also adds the new version to `apps/docs/content/getting-started/releases.mdx` with a brief description derived from the release intro paragraph. 2. **SDK release workflow documentation** — documents the two-pass pattern used during SDK releases: first run finalizes `next.mdx` before NPM publish, second run archives, updates the index, resets `next.mdx`, and backfills PRs that landed during the freeze. ### Change type - [x] `other` ### Test plan - [ ] Unit tests - [ ] End to end tests ### Code changes | Section | LOC change | | --- | --- | | Config/tooling | +20 / -1 |
1 parent 7b2687a commit 9204c4b

1 file changed

Lines changed: 20 additions & 1 deletion

File tree

  • .claude/skills/update-release-notes

.claude/skills/update-release-notes/SKILL.md

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,12 @@ If a new release was published since `last_version` in `next.mdx`:
5656
- Set `title` to the version
5757
- Update dates
5858
- Add the GitHub release link after frontmatter
59-
3. Reset `next.mdx`:
59+
3. Add the new version to the releases index at `apps/docs/content/getting-started/releases.mdx`:
60+
- Add a line at the top of the appropriate `## v{major}.x` section
61+
- Format: `- [vX.Y](/releases/vX.Y.0) - Brief description`
62+
- The description should be a short summary of the release highlights from the intro paragraph (3-5 key features, comma-separated)
63+
- If a new major version section is needed, create it above the previous one
64+
4. Reset `next.mdx`:
6065
- Update `last_version` field to the new release
6166
- Clear the content sections
6267
- Keep the file structure for accumulating new changes
@@ -173,6 +178,20 @@ Then create the PR following the standards in `@.claude/skills/write-pr/SKILL.md
173178

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

181+
## SDK release workflow
182+
183+
During an SDK release, this skill is run **twice** to get the docs site into its post-release state:
184+
185+
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.
186+
2. **Publish the release to NPM** — this happens outside of this skill.
187+
3. **Second run** — now that the release is published, the status script will detect `needs_archive: true`. This run:
188+
- Archives `next.mdx` to a versioned file (e.g., `v4.5.0.mdx`)
189+
- Adds the new version to the releases index (`releases.mdx`)
190+
- Resets `next.mdx` with the new `last_version`
191+
- Finds PRs that landed on `main` during the freeze (since the release tag) and adds them to the fresh `next.mdx`
192+
193+
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.
194+
176195
## References
177196

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

0 commit comments

Comments
 (0)