docs: improve release note guidance#73
Merged
Merged
Conversation
Why v1.0.1 generated a low-level release note because several review follow-up commits were visible as release bullets. User impact Maintainers and AI agents now have clearer rules for PR titles, commit bodies, and Release note lines before tagging. Verification - git diff --check Release note: skip
📝 WalkthroughWalkthroughAdds a "Release Note Plan" prompt to the PR template, updates agent/maintainer docs with rules for writing human-sized release notes and ChangesRelease Note Standards
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Why Generated release notes can inherit lower-case imperative commit subjects, which reads awkwardly in English release bullets. User impact Future generated release notes capitalize the first rendered character while still requiring clear human-written release wording. Verification - git-cliff --config .github/cliff.toml --latest --strip header - git diff --check Release note: skip
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/engineering.md`:
- Around line 108-111: Replace the ambiguous phrase "Review follow-up commits
should usually be `Release note: skip`" with a clearer wording such as
"Review-fix follow-up commits in a multi-commit PR should usually use `Release
note: skip`" so it's explicit this refers to commits addressing review feedback
(not the review process); update the sentence in the paragraph that currently
begins with "Keep multi-commit PRs readable..." and ensure the backtick style
for `Release note: skip` is preserved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ad4957c4-71d3-459e-bb16-80176b43e505
📒 Files selected for processing (5)
.github/cliff.tomlAGENTS.mdCLAUDE.mddocs/architecture.mddocs/engineering.md
Why CodeRabbit flagged that the phrase Review follow-up commits could be misread as referring to the review process instead of commits that address review feedback. User impact Maintainer guidance now makes the intended release-note skip rule clearer for multi-commit PRs. Verification - git diff --check Release note: skip
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
1 participant
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.
Pull Request
Summary
Improve the maintainer guidance and generator behavior that control release-note quality.
Release note:commit-body lines, not PR titles.Release note: skip.git-cliffoutput before tagging.Release Note Plan
Release note: skip
This is maintainer-process guidance. It should prevent future low-level release notes, but it does not change user-facing Agent Note behavior.
Type of Change
Checklist
Notes for Reviewers
I also manually rewrote the already-published
v1.0.0andv1.0.1GitHub Release bodies so those two public release notes read like product updates instead of implementation logs.Verification:
git diff --checkgit-cliff --config .github/cliff.toml --latest --strip headerSummary by CodeRabbit
🧑💬🤖 Agent Note
Total AI Ratio: ████████ 100%
Model:
gpt-5.4597c6f9docs: improve release note guidancefd938a6docs: capitalize generated release notes0047babdocs: clarify release note follow-up wording💬 Prompts & Responses (3 total)
597c6f9docs: improve release note guidancefd938a6docs: capitalize generated release notes0047babdocs: clarify release note follow-up wording