|
| 1 | +--- |
| 2 | +status: active |
| 3 | +created: 2025-12-11 |
| 4 | +updated: 2025-12-11 |
| 5 | +type: reference |
| 6 | +lifecycle: persistent |
| 7 | +description: Generate changelog draft from recent commits |
| 8 | +--- |
| 9 | + |
| 10 | +# Changelog Update |
| 11 | + |
| 12 | +Generate a changelog draft from git commits since the last CHANGELOG.md entry. |
| 13 | + |
| 14 | +## Your Task |
| 15 | + |
| 16 | +1. **Run the generator script**: |
| 17 | + ```bash |
| 18 | + ./scripts/generate-changelog-draft.sh |
| 19 | + ``` |
| 20 | + |
| 21 | +2. **Review the output**: |
| 22 | + - Verify the categorization makes sense (Added/Changed/Fixed) |
| 23 | + - Check that test hints are accurate and runnable |
| 24 | + - Look for any commits that were incorrectly filtered out |
| 25 | + |
| 26 | +3. **Enhance entries if needed**: |
| 27 | + - Improve descriptions to be user-friendly (not just commit messages) |
| 28 | + - Add better test commands where the heuristics failed |
| 29 | + - Group related entries (e.g., multiple tools added together) |
| 30 | + |
| 31 | +4. **Present the draft to the user**: |
| 32 | + Show the enhanced draft in a code block: |
| 33 | + ```markdown |
| 34 | + ## [YYYY-MM-DD] |
| 35 | + |
| 36 | + ### Added |
| 37 | + - Description with test hint |
| 38 | + |
| 39 | + ### Changed |
| 40 | + - Description |
| 41 | + |
| 42 | + ### Fixed |
| 43 | + - Description with test hint |
| 44 | + ``` |
| 45 | + |
| 46 | +5. **Ask for approval**: |
| 47 | + - Options: Append to CHANGELOG.md, Edit first, Skip |
| 48 | + - If approved, update the `[Unreleased]` section in CHANGELOG.md |
| 49 | + |
| 50 | +## Filtering Rules |
| 51 | + |
| 52 | +The script follows these rules (you should verify they make sense): |
| 53 | + |
| 54 | +| Type | Include? | Category | |
| 55 | +|------|----------|----------| |
| 56 | +| `feat:` | Always | Added | |
| 57 | +| `fix:` | Always | Fixed | |
| 58 | +| `perf:` | Always | Changed | |
| 59 | +| `chore:` | Only if packages.nix changed | Changed | |
| 60 | +| `refactor:` | Only if user-facing | Changed | |
| 61 | +| `docs:`, `ci:`, `test:` | Never | - | |
| 62 | + |
| 63 | +## Enhancement Guidelines |
| 64 | + |
| 65 | +When improving the raw output: |
| 66 | + |
| 67 | +**Good test hints** (specific, runnable): |
| 68 | +``` |
| 69 | +(Test: `echo "hello" | wl-copy && wl-paste`) |
| 70 | +(Test: Connect Android device, run `adb devices`) |
| 71 | +(Test: Launch Kooha from application menu) |
| 72 | +``` |
| 73 | + |
| 74 | +**Bad test hints** (vague, not actionable): |
| 75 | +``` |
| 76 | +(Test: Verify it works) |
| 77 | +(Test: Check the feature) |
| 78 | +``` |
| 79 | + |
| 80 | +**Good descriptions** (user-focused): |
| 81 | +``` |
| 82 | +- `wl-clipboard` - Copy/paste in terminal for Wayland sessions |
| 83 | +- ADB support for Android development and debugging |
| 84 | +``` |
| 85 | + |
| 86 | +**Bad descriptions** (developer-focused): |
| 87 | +``` |
| 88 | +- add wl-clipboard and kooha, simplify fish config |
| 89 | +- enable ADB for Android development |
| 90 | +``` |
| 91 | + |
| 92 | +## CHANGELOG.md Format |
| 93 | + |
| 94 | +Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/): |
| 95 | + |
| 96 | +```markdown |
| 97 | +## [Unreleased] |
| 98 | + |
| 99 | +### Planned |
| 100 | +- (Future work items) |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +## [2025-12-11] |
| 105 | + |
| 106 | +### Added |
| 107 | +- New feature descriptions... |
| 108 | +``` |
| 109 | + |
| 110 | +## Important |
| 111 | + |
| 112 | +- **NEVER auto-commit** - Always show draft and wait for approval |
| 113 | +- **Preserve existing content** - Only add to `[Unreleased]` section |
| 114 | +- **Date new entries** - When moving from Unreleased to dated section |
0 commit comments