Skip to content

Commit b76c360

Browse files
justin808claude
justin808
and
claude
committed
Add /update-changelog command for guided changelog updates
Adds comprehensive slash command based on Shakapacker's implementation with React on Rails-specific improvements: **New slash command**: `/update-changelog` - Provides guided workflow for adding changelog entries - Ensures correct formatting (no hash in PR numbers) - Validates user-visible vs non-user-visible changes - Handles version boundaries and beta releases - Includes real examples from the codebase - Documents both standard and custom section headers **Improvements over Shakapacker version**: - Updated PR link format (no hash symbol) - Documents all React on Rails custom section headers - References `bundle exec rake update_changelog` for version management - Includes actual examples from CHANGELOG.md - Added grep command for viewing real formatting examples **Updated CLAUDE.md**: - References `/update-changelog` command for guided updates - Separates version management (rake task) from entry creation (command) - Maintains concise 6-bullet format This makes changelog updates consistent and reduces errors by providing an interactive guided process with comprehensive documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 481c8d8 commit b76c360

File tree

2 files changed

+258
-1
lines changed

2 files changed

+258
-1
lines changed

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

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# Update Changelog
2+
3+
You are helping to add an entry to the CHANGELOG.md file for the React on Rails project.
4+
5+
## Critical Requirements
6+
7+
1. **User-visible changes only**: Only add changelog entries for user-visible changes:
8+
9+
- New features
10+
- Bug fixes
11+
- Breaking changes
12+
- Deprecations
13+
- Performance improvements
14+
- Security fixes
15+
- Changes to public APIs or configuration options
16+
17+
2. **Do NOT add entries for**:
18+
- Linting fixes
19+
- Code formatting
20+
- Internal refactoring
21+
- Test updates
22+
- Documentation fixes (unless they fix incorrect docs about behavior)
23+
- CI/CD changes
24+
25+
## Formatting Requirements
26+
27+
### Entry Format
28+
29+
Each changelog entry MUST follow this exact format:
30+
31+
```markdown
32+
- **Bold description of change**. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username). Optional additional context or details.
33+
```
34+
35+
**Important formatting rules**:
36+
37+
- Start with a dash and space: `- `
38+
- Use **bold** for the main description
39+
- End the bold description with a period before the link
40+
- Always link to the PR: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)` - **NO hash symbol**
41+
- Always link to the author: `by [username](https://github.com/username)`
42+
- 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
44+
45+
### Breaking Changes Format
46+
47+
For breaking changes, use this format:
48+
49+
```markdown
50+
- **Feature Name**: Description of the breaking change. See migration guide below. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username).
51+
52+
**Migration Guide:**
53+
54+
1. Step one
55+
2. Step two
56+
```
57+
58+
### Category Organization
59+
60+
Entries should be organized under these section headings. The project uses both standard and custom headings:
61+
62+
**Standard headings** (from keepachangelog.com):
63+
64+
- `#### Added` - New features
65+
- `#### Changed` - Changes to existing functionality
66+
- `#### Deprecated` - Deprecation notices
67+
- `#### Removed` - Removed features
68+
- `#### Fixed` - Bug fixes
69+
- `#### Security` - Security-related changes
70+
71+
**Custom headings** (project-specific):
72+
73+
- `#### Breaking Changes` - Breaking changes only
74+
- `#### New Features` - New features
75+
- `#### Bug Fixes` - Bug fixes
76+
- `#### Security Enhancements` - Security improvements
77+
- `#### API Improvements` - API changes and improvements
78+
- `#### Developer Experience` - DX improvements
79+
- `#### Generator Improvements` - Generator changes
80+
- `#### Code Improvements` - Code quality improvements
81+
- `#### Performance` - Performance improvements
82+
- `#### Pro License Features` - Pro-only features
83+
84+
**Choose the header that best describes your change.** Use custom headers for complex changes that benefit from more specific categorization.
85+
86+
**Only include section headings that have entries.**
87+
88+
### Version Management
89+
90+
After adding entries, use the rake task to manage version headers:
91+
92+
```bash
93+
bundle exec rake update_changelog
94+
```
95+
96+
This will:
97+
98+
- Add headers for the new version
99+
- Update version diff links at the bottom of the file
100+
101+
## Process
102+
103+
### For Regular Changelog Updates
104+
105+
1. **Determine the correct version tag to compare against**:
106+
107+
- First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
108+
- Find the latest version tag and its date
109+
- Compare main branch date to the tag date
110+
- If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
111+
- **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
112+
113+
2. **Check commits and version boundaries**:
114+
115+
- Run `git log --oneline LAST_TAG..master` to see commits since the last release
116+
- Also check `git log --oneline master..LAST_TAG` to see if the tag is ahead of master
117+
- If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
118+
- Identify which commits contain user-visible changes
119+
- Extract PR numbers and author information from commit messages
120+
- **Never ask the user for PR details** - get them from the git history
121+
122+
3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
123+
124+
4. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
125+
126+
5. **Determine where entries should go**:
127+
128+
- If the latest version tag is NEWER than master branch, move entries from "Unreleased" to that version section
129+
- If master is ahead of the latest tag, add new entries to "Unreleased"
130+
- Always verify the version date in CHANGELOG.md matches the actual tag date
131+
132+
6. **Add or move entries** to the appropriate section under appropriate category headings.
133+
134+
- **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
135+
- **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
136+
- If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
137+
- Maintain the category order as defined above
138+
139+
7. **Verify formatting**:
140+
141+
- Bold description with period
142+
- Proper PR link (NO hash symbol)
143+
- Proper author link
144+
- Consistent with existing entries
145+
- File ends with a newline character
146+
147+
8. **Run linting** after making changes:
148+
149+
```bash
150+
bundle exec rubocop
151+
yarn run lint
152+
```
153+
154+
9. **Show the user** the added or moved entries and explain what was done.
155+
156+
### For Beta to Non-Beta Version Release
157+
158+
When releasing from beta to a stable version (e.g., v16.1.0-beta.3 → v16.1.0):
159+
160+
1. **Remove all beta version labels** from the changelog:
161+
162+
- Change `### [v16.1.0-beta.1]`, `### [v16.1.0-beta.2]`, etc. to a single `### [v16.1.0]` section
163+
- Combine all beta entries into the stable release section
164+
165+
2. **Consolidate duplicate entries**:
166+
167+
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
168+
- Remove redundant changelog entries for fixes to beta features
169+
- Keep the most recent/accurate description of each change
170+
171+
3. **Update version diff links** using `bundle exec rake update_changelog`
172+
173+
### For New Beta Version Release
174+
175+
When creating a new beta version, ask the user which approach to take:
176+
177+
**Option 1: Process changes since last beta**
178+
179+
- Only add entries for commits since the previous beta version
180+
- Maintains detailed history of what changed in each beta
181+
182+
**Option 2: Collapse all prior betas into current beta**
183+
184+
- Combine all beta changelog entries into the new beta version
185+
- Removes previous beta version sections
186+
- Cleaner changelog with less version noise
187+
188+
After the user chooses, proceed with that approach.
189+
190+
## Examples
191+
192+
Run this command to see real formatting examples from the codebase:
193+
194+
```bash
195+
grep -A 3 "^#### " CHANGELOG.md | head -30
196+
```
197+
198+
### Good Entry Example
199+
200+
```markdown
201+
- **Attribution Comment**: Added HTML comment attribution to Rails views containing React on Rails functionality. The comment automatically displays which version is in use (open source React on Rails or React on Rails Pro) and, for Pro users, shows the license status. This helps identify React on Rails usage across your application. [PR 1857](https://github.com/shakacode/react_on_rails/pull/1857) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
202+
```
203+
204+
### Entry with Sub-bullets Example
205+
206+
```markdown
207+
- **Server Bundle Security**: Added new configuration options for enhanced server bundle security and organization:
208+
- `server_bundle_output_path`: Configurable directory (relative to the Rails root) for server bundle output (default: "ssr-generated"). If set to `nil`, the server bundle will be loaded from the same public directory as client bundles. [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808)
209+
- `enforce_private_server_bundles`: When enabled, ensures server bundles are only loaded from private directories outside the public folder (default: false for backward compatibility) [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808)
210+
```
211+
212+
### Breaking Change Example
213+
214+
````markdown
215+
- **React on Rails Core Package**: Several Pro-only methods have been removed from the core package and are now exclusively available in the `react-on-rails-pro` package. If you're using any of the following methods, you'll need to migrate to React on Rails Pro:
216+
- `getOrWaitForComponent()`
217+
- `getOrWaitForStore()`
218+
- `getOrWaitForStoreGenerator()`
219+
- `reactOnRailsStoreLoaded()`
220+
- `streamServerRenderedReactComponent()`
221+
- `serverRenderRSCReactComponent()`
222+
223+
**Migration Guide:**
224+
225+
To migrate to React on Rails Pro:
226+
227+
1. Install the Pro package:
228+
229+
```bash
230+
yarn add react-on-rails-pro
231+
# or
232+
npm install react-on-rails-pro
233+
```
234+
````
235+
236+
2. Update your imports from `react-on-rails` to `react-on-rails-pro`:
237+
238+
```javascript
239+
// Before
240+
import ReactOnRails from 'react-on-rails';
241+
242+
// After
243+
import ReactOnRails from 'react-on-rails-pro';
244+
```
245+
246+
```
247+
248+
## Additional Notes
249+
250+
- Keep descriptions concise but informative
251+
- Focus on the "what" and "why", not the "how"
252+
- Use past tense for the description
253+
- Be consistent with existing formatting in the changelog
254+
- Always ensure the file ends with a trailing newline
255+
- See CHANGELOG.md lines 15-18 for additional contributor guidelines
256+
```

‎CLAUDE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
4646
- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
4747
- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
4848
- **Format**: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
49-
- **See CHANGELOG.md lines 15-18** for full guidelines and `bundle exec rake update_changelog` for version management
49+
- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
50+
- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
5051
- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
5152

5253
## ⚠️ FORMATTING RULES

0 commit comments

Comments
 (0)