release-notes
Installation
SKILL.md
Writing Release Notes & Changelog
This repo maintains two release artifacts that describe the same set of changes for different audiences:
| File | Audience | Tone | Length |
|---|---|---|---|
RELEASE_NOTES.md |
Product owners, operators, developers shipping the system | Narrative, benefit-first with technical depth | Detailed |
CHANGELOG.md |
Developers integrating against the APIs, auditors, release engineers | Terse, factual, PR-linked (Keep a Changelog format) | Compact |
Both files are updated in the same release pass from the same source of commits. The narrative in RELEASE_NOTES.md may group and re-order changes thematically; CHANGELOG.md preserves a flat, categorized list.
Branch Model & Why This Is Hard
This repo uses a squash-merge workflow: develop accumulates feature branches via merge commits, and when a release is cut, develop is squash-merged into main. This means main and develop have divergent git histories — you cannot do a simple git log main..develop to get a clean diff. Commit SHAs on main don't correspond to anything on develop.