You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/commands/update-changelog.md
+65-37Lines changed: 65 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,12 @@
1
1
# Update Changelog
2
2
3
-
You are helping to add an entry to the CHANGELOG.md file for the PackageJson project.
3
+
You are helping to add an entry to the CHANGELOG.md file for the PackageJson
4
+
project.
4
5
5
6
## Critical Requirements
6
7
7
-
1.**User-visible changes only**: Only add changelog entries for user-visible changes:
8
-
8
+
1.**User-visible changes only**: Only add changelog entries for user-visible
9
+
changes:
9
10
- New features
10
11
- Bug fixes
11
12
- Breaking changes
@@ -29,25 +30,33 @@ You are helping to add an entry to the CHANGELOG.md file for the PackageJson pro
29
30
Each changelog entry MUST follow this exact format:
30
31
31
32
```markdown
32
-
- **Bold description of change**. [PR 1818](https://github.com/shakacode/package_json/pull/1818) by [username](https://github.com/username). Optional additional context or details.
33
+
- **Bold description of change**.
34
+
[PR 1818](https://github.com/shakacode/package_json/pull/1818) by
35
+
[username](https://github.com/username). Optional additional context or
36
+
details.
33
37
```
34
38
35
39
**Important formatting rules**:
36
40
37
41
- Start with a dash and space: `- `
38
42
- Use **bold** for the main description
39
43
- End the bold description with a period before the link
40
-
- Always link to the PR: `[PR 1818](https://github.com/shakacode/package_json/pull/1818)` - **NO hash symbol**
- Always link to the author: `by [username](https://github.com/username)`
42
48
- End with a period after the author link
43
-
- Additional details can be added after the main entry, using proper indentation for multi-line entries
49
+
- Additional details can be added after the main entry, using proper indentation
50
+
for multi-line entries
44
51
45
52
### Breaking Changes Format
46
53
47
54
For breaking changes, use this format:
48
55
49
56
```markdown
50
-
- **Feature Name**: Description of the breaking change. See migration guide below. [PR 1818](https://github.com/shakacode/package_json/pull/1818) by [username](https://github.com/username).
57
+
- **Feature Name**: Description of the breaking change. See migration guide
58
+
below. [PR 1818](https://github.com/shakacode/package_json/pull/1818) by
59
+
[username](https://github.com/username).
51
60
52
61
**Migration Guide:**
53
62
@@ -57,7 +66,8 @@ For breaking changes, use this format:
57
66
58
67
### Category Organization
59
68
60
-
Entries should be organized under these section headings. The project uses both standard and custom headings:
69
+
Entries should be organized under these section headings. The project uses both
70
+
standard and custom headings:
61
71
62
72
**Standard headings** (from keepachangelog.com) - use these for most changes:
63
73
@@ -69,12 +79,14 @@ Entries should be organized under these section headings. The project uses both
69
79
-`#### Security` - Security-related changes
70
80
-`#### Improved` - Improvements to existing features
71
81
72
-
**Custom headings** (project-specific) - use sparingly when standard headings don't fit:
82
+
**Custom headings** (project-specific) - use sparingly when standard headings
83
+
don't fit:
73
84
74
85
-`#### Breaking Changes` - Breaking changes with migration guides
75
86
-`#### Performance` - Performance improvements
76
87
77
-
**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
88
+
**Prefer standard headings.** Only use custom headings when the change needs
89
+
more specific categorization.
78
90
79
91
**Only include section headings that have entries.**
80
92
@@ -96,41 +108,49 @@ This will:
96
108
### For Regular Changelog Updates
97
109
98
110
1.**Determine the correct version tag to compare against**:
99
-
100
-
- First, check the tag dates:`git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
111
+
- First, check the tag dates:
112
+
`git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
101
113
- Find the latest version tag and its date
102
114
- Compare main branch date to the tag date
103
-
- If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
104
-
-**CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead
115
+
- If the tag is NEWER than main, it means main needs to be updated to include
116
+
the tag's commits
117
+
-**CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in
118
+
the tag but not in the branch, as the tag may be ahead
105
119
106
120
2.**Check commits and version boundaries**:
107
-
108
-
- Run `git log --oneline LAST_TAG..main` to see commits since the last release
109
-
- Also check `git log --oneline main..LAST_TAG` to see if the tag is ahead of main
110
-
- If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
121
+
- Run `git log --oneline LAST_TAG..main` to see commits since the last
122
+
release
123
+
- Also check `git log --oneline main..LAST_TAG` to see if the tag is ahead of
124
+
main
125
+
- If the tag is ahead, entries in "Unreleased" section may actually belong to
126
+
that tagged version
111
127
- Identify which commits contain user-visible changes
112
128
- Extract PR numbers and author information from commit messages
113
129
-**Never ask the user for PR details** - get them from the git history
114
130
115
-
3.**Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
131
+
3.**Validate** that changes are user-visible (per the criteria above). If not
132
+
user-visible, skip those commits.
116
133
117
-
4.**Read the current CHANGELOG.md** to understand the existing structure and formatting.
134
+
4.**Read the current CHANGELOG.md** to understand the existing structure and
135
+
formatting.
118
136
119
137
5.**Determine where entries should go**:
120
-
121
-
- If the latest version tag is NEWER than main branch, move entries from "Unreleased" to that version section
138
+
- If the latest version tag is NEWER than main branch, move entries from
139
+
"Unreleased" to that version section
122
140
- If main is ahead of the latest tag, add new entries to "Unreleased"
123
141
- Always verify the version date in CHANGELOG.md matches the actual tag date
124
142
125
-
6.**Add or move entries** to the appropriate section under appropriate category headings.
126
-
127
-
-**CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
- If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
143
+
6.**Add or move entries** to the appropriate section under appropriate category
144
+
headings.
145
+
-**CRITICAL**: When moving entries from "Unreleased" to a version section,
146
+
merge them with existing entries under the same category heading
147
+
-**NEVER create duplicate section headings** (e.g., don't create two "###
148
+
Fixed" sections)
149
+
- If the version section already has a category heading (e.g., "### Fixed"),
150
+
add the moved entries to that existing section
130
151
- Maintain the category order as defined above
131
152
132
153
7.**Verify formatting**:
133
-
134
154
- Bold description with period
135
155
- Proper PR link (NO hash symbol)
136
156
- Proper author link
@@ -151,13 +171,13 @@ This will:
151
171
When releasing from beta to a stable version (e.g., v1.1.0-beta.3 → v1.1.0):
152
172
153
173
1.**Remove all beta version labels** from the changelog:
154
-
155
-
- Change `### [v1.1.0-beta.1]`, `### [v1.1.0-beta.2]`, etc. to a single`### [v1.1.0]` section
174
+
- Change `### [v1.1.0-beta.1]`, `### [v1.1.0-beta.2]`, etc. to a single
175
+
`### [v1.1.0]` section
156
176
- Combine all beta entries into the stable release section
157
177
158
178
2.**Consolidate duplicate entries**:
159
-
160
-
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
179
+
- If bug fixes or changes were made to features introduced in earlier betas,
180
+
keep only the final state
161
181
- Remove redundant changelog entries for fixes to beta features
162
182
- Keep the most recent/accurate description of each change
163
183
@@ -191,21 +211,29 @@ grep -A 3 "^#### " CHANGELOG.md | head -30
191
211
### Good Entry Example
192
212
193
213
```markdown
194
-
- **New feature description**: Added helpful functionality that users will appreciate. [PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username).
214
+
- **New feature description**: Added helpful functionality that users will
215
+
appreciate. [PR 123](https://github.com/shakacode/package_json/pull/123) by
216
+
[username](https://github.com/username).
195
217
```
196
218
197
219
### Entry with Sub-bullets Example
198
220
199
221
```markdown
200
-
- **Multi-part feature**: Added new configuration options for enhanced functionality:
201
-
- `option_name`: Description of the option and its purpose. [PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username)
202
-
- `another_option`: Description of another option. [PR 124](https://github.com/shakacode/package_json/pull/124) by [username](https://github.com/username)
222
+
- **Multi-part feature**: Added new configuration options for enhanced
223
+
functionality:
224
+
- `option_name`: Description of the option and its purpose.
225
+
[PR 123](https://github.com/shakacode/package_json/pull/123) by
226
+
[username](https://github.com/username)
227
+
- `another_option`: Description of another option.
228
+
[PR 124](https://github.com/shakacode/package_json/pull/124) by
229
+
[username](https://github.com/username)
203
230
```
204
231
205
232
### Breaking Change Example
206
233
207
234
```markdown
208
-
- **Method Removal**: Several deprecated methods have been removed. If you're using any of the following methods, you'll need to migrate:
235
+
- **Method Removal**: Several deprecated methods have been removed. If you're
236
+
using any of the following methods, you'll need to migrate:
0 commit comments