|
2 | 2 | name: changelog-cleanup |
3 | 3 | description: >- |
4 | 4 | Analyze and clean up the Upcoming Release section in CHANGELOG.md. Reviews |
5 | | - each entry for grammar and logic issues, then sorts entries into categories. |
6 | | - Use when the user mentions changelog cleanup, changelog sorting, release |
7 | | - notes review, or preparing a release. |
| 5 | + each entry for grammar and logic issues, then sorts entries into named |
| 6 | + sections. Use when the user mentions changelog cleanup, changelog sorting, |
| 7 | + release notes review, or preparing a release. |
8 | 8 | --- |
9 | 9 |
|
10 | 10 | # Changelog Cleanup |
11 | 11 |
|
12 | 12 | Cleans up the `## Upcoming Release` section of `CHANGELOG.md` in two phases: |
13 | | -grammar/logic review, then sorting by category. |
| 13 | +grammar/logic review, then sorting into named sections. |
| 14 | + |
| 15 | +## Changelog structure |
| 16 | + |
| 17 | +Each release is a `## ` heading (e.g., `## Upcoming Release`, `## 2.3.6`). |
| 18 | +Within a release, entries are organized under **named sections** — plain-text |
| 19 | +labels followed by a colon, each followed by a blank line and then bullet |
| 20 | +entries. Section names are **not fixed**; they vary between releases. Common |
| 21 | +examples include `New features:`, `Changes:`, `Bugfixes:`, but there may be |
| 22 | +others (e.g., `Deprecations:`, `Breaking changes:`, `Performance:`). |
| 23 | + |
| 24 | +Example structure: |
| 25 | + |
| 26 | +```markdown |
| 27 | +## 2.3.6 |
| 28 | + |
| 29 | +New features: |
| 30 | + |
| 31 | +- Entry one |
| 32 | + |
| 33 | +Changes: |
| 34 | + |
| 35 | +- Entry two |
| 36 | + |
| 37 | +Bugfixes: |
| 38 | + |
| 39 | +- Entry three |
| 40 | +- Entry four |
| 41 | +``` |
| 42 | + |
| 43 | +Older releases (before 2.3.6) use a legacy flat list of bullets with no named |
| 44 | +sections. That format is no longer valid for new releases. |
14 | 45 |
|
15 | 46 | ## Phase 1: Grammar and Logic Review |
16 | 47 |
|
17 | | -1. Read `CHANGELOG.md` and extract all entries under `## Upcoming Release` |
| 48 | +1. Read `CHANGELOG.md` and extract all content under `## Upcoming Release` |
18 | 49 | (stop at the next `## ` heading). |
19 | 50 | 2. For each entry, check for: |
20 | 51 | - Spelling and grammar mistakes |
21 | 52 | - Unclear or ambiguous phrasing |
22 | 53 | - Logical issues (e.g., an entry starting with "Fixed" that actually |
23 | 54 | describes a new feature, or contradictory statements) |
| 55 | + - Entries placed under the wrong section (e.g., a bug fix listed under |
| 56 | + "New features:") |
24 | 57 | 3. When an issue is found, use the `AskQuestion` tool to present the proposed |
25 | 58 | fix to the user. Provide two options: "Accept" and "Reject". |
26 | 59 | Batch related fixes into a single `AskQuestion` call when possible to |
27 | 60 | reduce round-trips, but keep each fix clearly labeled. |
28 | 61 | 4. Apply only accepted fixes. Do not modify entries the user rejects. |
29 | 62 |
|
30 | | -## Phase 2: Sort Entries |
| 63 | +## Phase 2: Sort Entries into Sections |
31 | 64 |
|
32 | | -After grammar/logic fixes are applied, sort entries into four groups. |
33 | | -Keep this exact order (no blank lines between groups): |
| 65 | +After grammar/logic fixes are applied, sort entries into named sections. |
| 66 | +Use these four sections in this exact order: |
34 | 67 |
|
35 | | -### Group 1 — New features and additions |
| 68 | +### Section 1 — `New features:` |
36 | 69 |
|
37 | 70 | Entries that semantically describe something new (e.g. `Added`), regardless of |
38 | 71 | the leading verb. |
39 | 72 |
|
40 | | -### Group 2 — Improvements and changes |
| 73 | +### Section 2 — `Changes:` |
41 | 74 |
|
42 | | -Entries that describe enhancing, changing, or updating existing behavior |
43 | | -(e.g. `Improved`, `Changed`, `Updated`), regardless of the leading verb. |
| 75 | +Entries that describe enhancing, changing, updating, removing, bumping |
| 76 | +dependencies, refactoring, or modifying existing behavior |
| 77 | +(e.g. `Improved`, `Changed`, `Updated`, `Removed`, `Bumped`, `Replaced`), |
| 78 | +regardless of the leading verb. |
44 | 79 |
|
45 | | -### Group 3 — Bug fixes |
| 80 | +### Section 3 — `Bugfixes:` |
46 | 81 |
|
47 | 82 | Entries that semantically describe fixing incorrect behavior (e.g. `Fixed`), |
48 | 83 | regardless of the leading verb. |
49 | 84 |
|
50 | | -### Group 4 — Other changes |
| 85 | +### Section 4 — Other (custom name) |
51 | 86 |
|
52 | | -Everything else: dependency bumps, refactors, removals, tooling. |
| 87 | +If there are entries that don't fit the three sections above, use the |
| 88 | +`AskQuestion` tool to ask the user what section name to use for them, or |
| 89 | +whether to fold them into one of the existing sections. |
53 | 90 |
|
54 | 91 | ### Sorting rules |
55 | 92 |
|
56 | 93 | - Use the first word after `- ` as a signal, but override when the meaning |
57 | | - clearly fits a different group. |
| 94 | + clearly fits a different section. |
58 | 95 | - Multi-line entries (parent + indented sub-bullets) stay as one unit. |
59 | | -- Preserve original relative order within each group. |
60 | | -- No blank lines between groups. |
| 96 | +- Preserve original relative order within each section. |
| 97 | +- Omit sections that have no entries (don't output an empty section heading). |
| 98 | +- Each section heading is followed by a blank line, then its bullet entries. |
| 99 | +- Separate sections from each other with a blank line after the last bullet. |
| 100 | + |
| 101 | +## Output format |
61 | 102 |
|
62 | | -## Example |
| 103 | +The final output under `## Upcoming Release` must look like: |
63 | 104 |
|
64 | 105 | ```markdown |
| 106 | +## Upcoming Release |
| 107 | + |
| 108 | +New features: |
| 109 | + |
65 | 110 | - Added support for OAuth tokens |
66 | 111 | - Added new `timeout` option |
| 112 | + |
| 113 | +Changes: |
| 114 | + |
67 | 115 | - Improved error details when OAuth fails |
68 | 116 | - Changed default `jsonColumnVariantParser` to `JSON.parse` |
| 117 | +- Bumped axios to 1.14.0 |
| 118 | + |
| 119 | +Bugfixes: |
| 120 | + |
69 | 121 | - Fixed a crash when loading config |
70 | 122 | - Fixed typo in error message |
71 | | -- Bumped axios to 1.14.0 |
72 | 123 | ``` |
0 commit comments