|
| 1 | +# Generate Release Notes |
| 2 | + |
| 3 | +Generate release notes from commits since the last version tag and write them to `.docs.local/RELEASE.md`. |
| 4 | + |
| 5 | +## Instructions |
| 6 | + |
| 7 | +1. **Find the latest version tag:** |
| 8 | + ```bash |
| 9 | + git describe --tags --abbrev=0 |
| 10 | + ``` |
| 11 | + |
| 12 | +2. **Get commits since that tag:** |
| 13 | + ```bash |
| 14 | + git log <tag>..HEAD --oneline --no-merges |
| 15 | + ``` |
| 16 | + |
| 17 | +3. **Write conversational release notes** to `.docs.local/RELEASE.md` following this style: |
| 18 | + |
| 19 | +### Writing Style |
| 20 | + |
| 21 | +**DO NOT** just list commits. Instead, write release notes that tell a story: |
| 22 | + |
| 23 | +- **Lead with what matters most** - Start with a brief intro paragraph highlighting the 2-3 most impactful changes |
| 24 | +- **Group related changes** - Combine multiple commits that work toward the same goal into a single, well-explained entry |
| 25 | +- **Explain the "why"** - Help users understand how changes benefit them, not just what changed |
| 26 | +- **Use natural language** - Write like you're telling a colleague about the release over coffee |
| 27 | +- **Highlight breaking changes prominently** - These need extra attention and migration guidance |
| 28 | + |
| 29 | +### Structure |
| 30 | + |
| 31 | +```markdown |
| 32 | +# Release Notes for vX.Y.Z |
| 33 | + |
| 34 | +<Opening paragraph: 1-3 sentences summarizing the release theme and most exciting changes> |
| 35 | + |
| 36 | +## Breaking Changes |
| 37 | + |
| 38 | +<If any: explain what changed, why, and how to migrate. Be helpful, not just factual.> |
| 39 | + |
| 40 | +## Highlights |
| 41 | + |
| 42 | +<The 2-4 most significant improvements, with context about why they matter> |
| 43 | + |
| 44 | +## Other Improvements |
| 45 | + |
| 46 | +<Grouped by area (e.g., "TUI", "CLI", "Performance") with brief descriptions> |
| 47 | + |
| 48 | +## Bug Fixes |
| 49 | + |
| 50 | +<Notable fixes, especially ones users might have encountered> |
| 51 | +``` |
| 52 | + |
| 53 | +### Linking to Commits and PRs |
| 54 | + |
| 55 | +Include links to commits or PRs so readers can dig deeper: |
| 56 | + |
| 57 | +1. **Get the GitHub repo URL:** |
| 58 | + ```bash |
| 59 | + git remote get-url origin |
| 60 | + ``` |
| 61 | + |
| 62 | +2. **Link to commits** using the short hash: |
| 63 | + ```markdown |
| 64 | + Fixed TUI crash on narrow terminals ([9e32a11](https://github.com/owner/repo/commit/9e32a11)) |
| 65 | + ``` |
| 66 | + |
| 67 | +3. **Link to PRs** when commits reference them (look for `(#123)` in commit messages): |
| 68 | + ```markdown |
| 69 | + Simplified bean linking ([#17](https://github.com/owner/repo/pull/17)) |
| 70 | + ``` |
| 71 | + |
| 72 | +When grouping multiple commits into one entry, link to the most significant commit or the PR that introduced the feature. |
| 73 | + |
| 74 | +### Example Tone |
| 75 | + |
| 76 | +Instead of: |
| 77 | +> - feat(tui): add status picker modal with 's' shortcut |
| 78 | +
|
| 79 | +Write: |
| 80 | +> **Quick status changes** — Press `s` in the TUI to instantly change a bean's status without leaving the list view. No more navigating to edit mode for simple updates. ([ad3382e](https://github.com/owner/repo/commit/ad3382e)) |
| 81 | +
|
| 82 | +### Version Bumping |
| 83 | + |
| 84 | +Suggest the next version based on: |
| 85 | +- **Major bump**: Breaking changes (but stay in 0.x.y for pre-1.0 projects) |
| 86 | +- **Minor bump**: New features |
| 87 | +- **Patch bump**: Only bug fixes |
| 88 | + |
| 89 | +## Output |
| 90 | + |
| 91 | +**Overwrite** `.docs.local/RELEASE.md` with freshly generated release notes (create the directory if needed). Do not read or incorporate existing contents - always generate from scratch based on the git history. |
0 commit comments