docs: add prepare-release-notes skill and document it in the release how-to#1100
Open
tbouffard wants to merge 2 commits into
Open
docs: add prepare-release-notes skill and document it in the release how-to#1100tbouffard wants to merge 2 commits into
tbouffard wants to merge 2 commits into
Conversation
…how-to Add a Claude Code skill (.claude/skills/prepare-release-notes) that drafts a GitHub release notes body for maxGraph from the commit history, the CHANGELOG and the linked pull requests, and optionally updates the GitHub draft release. The skill: - determines the target and previous versions and the commit range - drafts breaking changes and deprecations, cross-checked against CHANGELOG.md, with before/after migration snippets - drafts feature highlights from feat commits and their linked PRs, validated with the user, with real code examples - excludes bug fixes by default, listing them for a case-by-case decision - drafts the one-line summary reused in the CHANGELOG and on the release page - computes the example bundle size table (current version, plus the previous version for comparison) - wraps prose at 160 characters and never invents PR numbers or content not backed by commits/PRs - finalizes the GitHub draft release, preserving the Resources section and the actual release date Also document the two-phase usage in packages/website/docs/development/release.md (prepare the content during preparation, finalize the GitHub release after tag and npm publish) and ignore the local RELEASE_NOTES_DRAFT.md output.
tbouffard
added
the
chore
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughAdds a Claude Code skill for preparing GitHub release notes, updates release-process documentation to match it, and ignores the local draft file used by the workflow. ChangesRelease notes preparation workflow
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dc8066fc-a166-4352-a816-3dab4c7151fa
📒 Files selected for processing (3)
.claude/skills/prepare-release-notes/SKILL.md.gitignorepackages/website/docs/development/release.md
Comment on lines
+66
to
+93
| - List commits whose title contains `!` per semver (`type!:` or `type(scope)!:`): | ||
| `git log v<previous>..HEAD --oneline | grep -E '^[a-f0-9]+ [a-z]+(\([^)]+\))?!:'` | ||
| - Cross-check `CHANGELOG.md` (the `## Unreleased` section, plus the target version section if already | ||
| added): verify every breaking change **and** every deprecation notice from the commits has a | ||
| matching CHANGELOG entry. **Flag any missing entry** to the user rather than silently filling it. | ||
| - Fill the "Breaking changes", "Removal of deprecated API", and "Deprecated APIs" sections. Drop a | ||
| section entirely if it has no content. | ||
| - Add a before/after migration snippet for any breaking change that alters call sites (see Core rules). | ||
| - Read the linked PR for the full rationale and impact, not just the commit message (see Core rules). | ||
|
|
||
| ### 4. Features (validate with the user first) | ||
|
|
||
| - Extract `feat` commits: `git log v<previous>..HEAD --oneline | grep -E '^[a-f0-9]+ feat(\([^)]+\))?!?:'` | ||
| - For each candidate, read the linked PR (see Core rules): its description often has context, code | ||
| examples and screenshots not in the commit message, which can be reused directly in the highlight. | ||
| - Produce a **pre-list** of candidate highlights and present it to the user to validate the level of | ||
| detail **before** writing the prose. Do not write the Highlights section until the user approves. | ||
| - Link each highlight to its real PR (`For more details, see #<PR_NUMBER>.`), taken from the commit | ||
| (merge commits and squashed commits usually carry the `(#NNNN)` suffix). No PR number found → leave | ||
| a `TODO`. | ||
| - For API-facing highlights (new helper, new option), include a before/after code example (see Core | ||
| rules). | ||
|
|
||
| ### 5. Bug fixes (excluded by default) | ||
|
|
||
| - Do **not** document bug fixes by default. | ||
| - Still present the list of `fix` commits to the user so they can decide, case by case, which (if any) | ||
| deserve a mention: `git log v<previous>..HEAD --oneline | grep -E '^[a-f0-9]+ fix(\([^)]+\))?!?:'` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Make the commit filters non-fatal when they match nothing.
These grep pipelines return exit 1 for valid releases with no breaking/feature/fix commits, which can abort the workflow before the draft is assembled. Please make the lookups tolerate empty results.
Possible fix
- git log v<previous>..HEAD --oneline | grep -E '...'
+ git log v<previous>..HEAD --oneline | grep -E '...' || trueGitHub renders a single newline in release notes as a visible line break, so hard-wrapping paragraphs shows mid-sentence breaks in the published notes. Reverse the earlier 160-character wrap rule: keep each paragraph and list item on a single line (code fences and tables are naturally multi-line and unaffected).
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add a
prepare-release-notesClaude Code skill (.claude/skills/prepare-release-notes) that drafts the GitHub release notes body for a maxGraph release, and document how to use it in the release how-to page.Why
Preparing release notes is a manual, error-prone step: gathering breaking changes, deprecations and highlights from the commit history, cross-checking the CHANGELOG, computing the example bundle sizes, and finally updating the GitHub draft release without clobbering its auto-generated content. This skill encodes that workflow so it is repeatable and consistent.
What the skill does
CHANGELOG.md, with before/after migration snippets.featcommits and their linked PRs (mining the PR body for context, code examples and screenshots), validated with the user before writing.Resourcessection and the actual release date set by the workflow.Docs
packages/website/docs/development/release.mdnow documents the two-phase usage: prepare the content during the preparation step, then finalize the GitHub release after the tag is pushed and the npm package is published. A few related anchors and wording were fixed while there.Notes
The skill was refined against a real dry run of the upcoming 0.24.0 release. The local
RELEASE_NOTES_DRAFT.mdoutput is added to.gitignore.Summary by CodeRabbit
Documentation
Resourcessection and the original release date.Chores