Skip to content

Commit 85372a4

Browse files
justin808claude
justin808
and
claude
authored
Add /update-changelog slash command for consistent changelog management (#794)
## Summary - Adds a new `/update-changelog` slash command that provides comprehensive guidance for updating CHANGELOG.md - Ensures consistency with project standards defined in CLAUDE.md - Helps maintain proper formatting and organization across all changelog entries - Automates PR detail extraction from git history - Handles beta version workflows and consolidation ## Key Features ### Clear Criteria - Distinguishes between user-visible changes (features, bug fixes, breaking changes) that need changelog entries - Explicitly excludes non-user-visible changes (linting, formatting, refactoring, tests) ### Formatting Requirements - Exact format for entries: bold description, PR links, author links - Special format for breaking changes with migration guide links - Category organization (Breaking Changes, Added, Changed, Fixed, etc.) - Multi-line entry indentation guidelines ### Version Management - Instructions for updating version diff links at the bottom of CHANGELOG.md - Guidelines for creating new version sections - Proper unreleased section maintenance ### Automated Workflow - **Never asks for PR details** - extracts from git history automatically - Checks commits on main/master since last release - Identifies user-visible changes from commit messages ### Beta Release Handling **Beta to Stable Release**: - Removes all beta version labels - Consolidates duplicate entries - Keeps only final state of changes **New Beta Version**: - Option 1: Process only changes since last beta (detailed history) - Option 2: Collapse all prior betas into current beta (cleaner changelog) ### Examples - Good entry examples showing proper formatting - Breaking change examples with migration guide links - Demonstrates consistency with existing entries ## Benefits - **Consistency**: All changelog entries follow the same format - **Quality**: Ensures only user-visible changes are documented - **Efficiency**: Reduces back-and-forth on PR reviews about changelog format - **Automation**: Extracts PR details from git history automatically - **Documentation**: Clear examples and guidelines for contributors - **Maintenance**: Easier to maintain version diff links - **Beta Support**: Handles beta version workflows systematically ## Test Plan - [x] Created slash command file at `.claude/commands/update-changelog.md` - [x] Verified formatting matches existing changelog entries - [x] Included all requirements from project CLAUDE.md files - [x] Added comprehensive examples - [x] File ends with trailing newline - [x] Added automated git history extraction workflow - [x] Added beta version handling workflows 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <[email protected]>
1 parent 5c7fe32 commit 85372a4

File tree

1 file changed

+171
-0
lines changed

1 file changed

+171
-0
lines changed

‎.claude/commands/update-changelog.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Update Changelog
2+
3+
You are helping to add an entry to the CHANGELOG.md file for the Shakapacker project.
4+
5+
## Critical Requirements
6+
7+
1. **User-visible changes only**: Only add changelog entries for user-visible changes:
8+
- New features
9+
- Bug fixes
10+
- Breaking changes
11+
- Deprecations
12+
- Performance improvements
13+
- Security fixes
14+
- Changes to public APIs or configuration options
15+
16+
2. **Do NOT add entries for**:
17+
- Linting fixes
18+
- Code formatting
19+
- Internal refactoring
20+
- Test updates
21+
- Documentation fixes (unless they fix incorrect docs about behavior)
22+
- CI/CD changes
23+
24+
## Formatting Requirements
25+
26+
### Entry Format
27+
28+
Each changelog entry MUST follow this exact format:
29+
30+
```markdown
31+
- **Bold description of change**. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username). Optional additional context or details.
32+
```
33+
34+
**Important formatting rules**:
35+
36+
- Start with a dash and space: `- `
37+
- Use **bold** for the main description
38+
- End the bold description with a period before the link
39+
- Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)`
40+
- Always link to the author: `by [username](https://github.com/username)`
41+
- End with a period after the author link
42+
- Additional details can be added after the main entry, using proper indentation for multi-line entries
43+
44+
### Breaking Changes Format
45+
46+
For breaking changes, use this format:
47+
48+
```markdown
49+
- **Breaking**: Description of the breaking change. See [Migration Guide](docs/vX_upgrade.md) for migration instructions. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username).
50+
```
51+
52+
### Category Organization
53+
54+
Entries should be organized under these section headings in order of priority:
55+
56+
1. `### ⚠️ Breaking Changes` - Breaking changes only
57+
2. `### Added` - New features
58+
3. `### Changed` - Changes to existing functionality
59+
4. `### Improved` - Improvements to existing features
60+
5. `### Security` - Security-related changes
61+
6. `### Fixed` - Bug fixes
62+
7. `### Deprecated` - Deprecation notices
63+
8. `### Removed` - Removed features
64+
65+
**Only include section headings that have entries.**
66+
67+
### Version Links
68+
69+
After adding an entry to the `## [Unreleased]` section, ensure the version diff links at the bottom of the file are correct.
70+
71+
The format at the bottom should be:
72+
73+
```markdown
74+
[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0...main
75+
[v9.3.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0
76+
```
77+
78+
When a new version is released:
79+
80+
1. Change `[Unreleased]` heading to `## [vX.Y.Z] - Month Day, Year`
81+
2. Add a new `## [Unreleased]` section at the top
82+
3. Update the `[Unreleased]` link to compare from the new version
83+
4. Add a new version link for the released version
84+
85+
## Process
86+
87+
### For Regular Changelog Updates
88+
89+
1. **Check commits since last release**:
90+
- Run `git log` to see commits on main/master since the last released version
91+
- Identify which commits contain user-visible changes
92+
- Extract PR numbers and author information from commit messages
93+
- **Never ask the user for PR details** - get them from the git history
94+
95+
2. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
96+
97+
3. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
98+
99+
4. **Add entries** to the `## [Unreleased]` section under appropriate category headings.
100+
101+
5. **Verify formatting**:
102+
- Bold description with period
103+
- Proper PR link
104+
- Proper author link
105+
- Consistent with existing entries
106+
- File ends with a newline character
107+
108+
6. **Run linting** after making changes:
109+
110+
```bash
111+
yarn lint
112+
```
113+
114+
7. **Show the user** the added entries.
115+
116+
### For Beta to Non-Beta Version Release
117+
118+
When releasing from beta to a stable version (e.g., v9.1.0-beta.3 → v9.1.0):
119+
120+
1. **Remove all beta version labels** from the changelog:
121+
- Change `## [v9.1.0-beta.1]`, `## [v9.1.0-beta.2]`, etc. to a single `## [v9.1.0]` section
122+
- Combine all beta entries into the stable release section
123+
124+
2. **Consolidate duplicate entries**:
125+
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
126+
- Remove redundant changelog entries for fixes to beta features
127+
- Keep the most recent/accurate description of each change
128+
129+
3. **Update version diff links** at the bottom to point to the stable version
130+
131+
### For New Beta Version Release
132+
133+
When creating a new beta version, ask the user which approach to take:
134+
135+
**Option 1: Process changes since last beta**
136+
137+
- Only add entries for commits since the previous beta version
138+
- Maintains detailed history of what changed in each beta
139+
140+
**Option 2: Collapse all prior betas into current beta**
141+
142+
- Combine all beta changelog entries into the new beta version
143+
- Removes previous beta version sections
144+
- Cleaner changelog with less version noise
145+
146+
After the user chooses, proceed with that approach.
147+
148+
## Examples
149+
150+
### Good Entry Example
151+
152+
```markdown
153+
- **Enhanced error handling for better security and debugging**. [PR #786](https://github.com/shakacode/shakapacker/pull/786) by [justin808](https://github.com/justin808).
154+
- Path validation now properly reports permission errors instead of silently handling them
155+
- Module loading errors now include original error context for easier troubleshooting
156+
- Improved security by only catching ENOENT errors in path resolution, rethrowing permission and access errors
157+
```
158+
159+
### Breaking Change Example
160+
161+
```markdown
162+
- **Breaking: SWC default configuration now uses `loose: false`**. [PR #658](https://github.com/shakacode/shakapacker/pull/658) by [justin808](https://github.com/justin808). See [v9 Upgrade Guide - SWC Loose Mode](./docs/v9_upgrade.md#swc-loose-mode-breaking-change-v910) for migration details.
163+
```
164+
165+
## Additional Notes
166+
167+
- Keep descriptions concise but informative
168+
- Focus on the "what" and "why", not the "how"
169+
- Use past tense for the description
170+
- Be consistent with existing formatting in the changelog
171+
- Always ensure the file ends with a trailing newline

0 commit comments

Comments
 (0)