Skip to content

Update changelog guidelines with formatting and context rules #556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timche merged 2 commits into from
Apr 28, 2026
Merged

Update changelog guidelines with formatting and context rules #556

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8f5474d
document release notes conventions for kbd shortcuts, same-release fi…
claude Apr 28, 2026
7364de5
note that release notes should be wrapped in a fenced code block for …
claude Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ This installs dependencies and runs postinstall scripts (including the lefthook
## Release Notes

- Release notes live only on GitHub Releases — do not commit a `RELEASE_NOTES.md` or `CHANGELOG.md` file. Match the style of recent published releases at https://github.com/zoidsh/meru/releases.
- Output the release notes in chat for pasting into the GitHub release — do not write them to a file in the repo.
- Output the release notes in chat for pasting into the GitHub release — do not write them to a file in the repo. Wrap the notes in a fenced markdown code block so the raw markdown can be copied directly into the GitHub release.
- Structure: use `## Added`, `## Changed`, `## Fixed`, `## Internal Changes` sections (in that order, omit unused ones). Skip `## Internal Changes` entirely when nothing affects end users (e.g. CI, CLAUDE.md, repo tooling).
- Classify each change correctly:
- `Added` — new feature or capability
Expand All @@ -165,3 +165,6 @@ This installs dependencies and runs postinstall scripts (including the lefthook
- Reference settings paths as `Settings... → Section → Option`.
- Group related bullets next to each other (e.g. all Google Apps changes together).
- Use sub-bullets for details: options list, defaults, keyboard shortcuts, behavior nuances. Always state the default for new options.
- Drop fixes to code newly introduced in the same release — a bug that only existed between merge and tag is invisible to users upgrading from the previous public release.
- Wrap keyboard shortcuts in `<kbd>` tags and write them per platform: `<kbd>Cmd</kbd>+<kbd>F</kbd> on macOS, <kbd>Ctrl</kbd>+<kbd>F</kbd> on Windows/Linux`.
- When reverting or removing a previously released feature, include the reason inline so users who relied on it understand the change.
Loading