Skip to content

Commit 24496cd

Browse files
justin808claude
justin808
and
claude
authored
Add changelog guidelines to CLAUDE.md (#1867)
* Add changelog guidelines to CLAUDE.md Following the Shakapacker PR #742 guidelines, this adds comprehensive changelog documentation requirements to CLAUDE.md: - Changelog entries required for user-visible changes only (features, bug fixes, breaking changes, deprecations, performance improvements) - No entries needed for linting, formatting, internal refactoring, tests, or documentation fixes - Format requirements: PR links, author links, consistent formatting - Breaking changes: bold formatting with migration guide links - Version release: update version diff links This ensures consistent, high-quality changelog maintenance across the project. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Fix changelog guidelines: PR format and automation reference Fixes identified in code review: 1. PR link format: Changed from `[PR #123]` to `[PR 1818]` (no hash) - Analysis shows 165 entries without hash vs only 7 with hash - Aligns with actual project standard 2. Added reference to `bundle exec rake update_changelog` - This is the existing automation for updating version headers - Mentioned in CHANGELOG.md line 18 but was missing from guidelines 3. Verified file ends with newline (required per CLAUDE.md) These changes ensure guidelines match actual usage and reference existing automation tools. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Enhance changelog guidelines with comprehensive documentation Following code review recommendations, this adds: 1. **Section header guidance**: Documents both standard keepachangelog.com headers (Added, Changed, Deprecated, Removed, Fixed, Security) and project-specific headers (Breaking Changes, New Features, Bug Fixes, Security Enhancements, API Improvements, etc.) 2. **Complete format examples**: Three real-world examples showing: - Simple entry format - Breaking change with migration guide - Entry with sub-bullets All examples verified against actual CHANGELOG.md patterns 3. **Cross-reference**: Added reference to CHANGELOG.md lines 15-18 for contributor guidelines and keepachangelog.com format 4. **Better organization**: Restructured into subsections (Section Headers, Format Requirements, Entry Format Examples) for easier reference These enhancements make the guidelines actionable and ensure consistent, high-quality changelog entries. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Simplify changelog section to conserve space Reduces the changelog section from ~50 lines to 5 concise bullets: - Consolidates what to include/exclude into one line each - Provides format example inline instead of separate section - References CHANGELOG.md lines 15-18 for full guidelines - Points to existing `bundle exec rake update_changelog` task - Includes grep command to view real formatting examples This saves space while making the guidelines more actionable by pointing developers to existing tools and real examples rather than duplicating information. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * 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]> * Fix update-changelog command: remove redundancy and fix formatting Addresses code review feedback: 1. **Removed redundant section headers**: - "New Features" (redundant with standard "Added") - "Bug Fixes" (redundant with standard "Fixed") - "Security Enhancements" (redundant with standard "Security") - "Code Improvements" (internal, not user-visible) 2. **Added "Improved" to standard headers** (used 9 times in CHANGELOG.md) 3. **Emphasized standard headers**: Updated guidance to prefer standard keepachangelog.com headers and use custom ones sparingly 4. **Fixed broken markdown formatting**: - Corrected triple/quadruple backtick issues in Breaking Change example - Removed nested code blocks that broke rendering - Simplified code examples within the markdown example 5. **Final header list**: - Standard: Added, Changed, Deprecated, Removed, Fixed, Security, Improved - Custom: Breaking Changes, API Improvements, Developer Experience, Generator Improvements, Performance, Pro License Features This reduces confusion and ensures the command guides developers to use consistent, standard headers while keeping legitimate project-specific headers for special cases. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
1 parent 7825688 commit 24496cd

File tree

2 files changed

+251
-0
lines changed

2 files changed

+251
-0
lines changed

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

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
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) - use these for most changes:
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+
- `#### Improved` - Improvements to existing features
71+
72+
**Custom headings** (project-specific) - use sparingly when standard headings don't fit:
73+
74+
- `#### Breaking Changes` - Breaking changes with migration guides
75+
- `#### API Improvements` - API changes and improvements
76+
- `#### Developer Experience` - Developer workflow improvements
77+
- `#### Generator Improvements` - Generator-specific changes
78+
- `#### Performance` - Performance improvements
79+
- `#### Pro License Features` - React on Rails Pro features
80+
81+
**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
82+
83+
**Only include section headings that have entries.**
84+
85+
### Version Management
86+
87+
After adding entries, use the rake task to manage version headers:
88+
89+
```bash
90+
bundle exec rake update_changelog
91+
```
92+
93+
This will:
94+
95+
- Add headers for the new version
96+
- Update version diff links at the bottom of the file
97+
98+
## Process
99+
100+
### For Regular Changelog Updates
101+
102+
1. **Determine the correct version tag to compare against**:
103+
104+
- First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
105+
- Find the latest version tag and its date
106+
- Compare main branch date to the tag date
107+
- If the tag is NEWER than main, it means main needs to be updated to include the tag's commits
108+
- **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
109+
110+
2. **Check commits and version boundaries**:
111+
112+
- Run `git log --oneline LAST_TAG..master` to see commits since the last release
113+
- Also check `git log --oneline master..LAST_TAG` to see if the tag is ahead of master
114+
- If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version
115+
- Identify which commits contain user-visible changes
116+
- Extract PR numbers and author information from commit messages
117+
- **Never ask the user for PR details** - get them from the git history
118+
119+
3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits.
120+
121+
4. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
122+
123+
5. **Determine where entries should go**:
124+
125+
- If the latest version tag is NEWER than master branch, move entries from "Unreleased" to that version section
126+
- If master is ahead of the latest tag, add new entries to "Unreleased"
127+
- Always verify the version date in CHANGELOG.md matches the actual tag date
128+
129+
6. **Add or move entries** to the appropriate section under appropriate category headings.
130+
131+
- **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
132+
- **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
133+
- If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
134+
- Maintain the category order as defined above
135+
136+
7. **Verify formatting**:
137+
138+
- Bold description with period
139+
- Proper PR link (NO hash symbol)
140+
- Proper author link
141+
- Consistent with existing entries
142+
- File ends with a newline character
143+
144+
8. **Run linting** after making changes:
145+
146+
```bash
147+
bundle exec rubocop
148+
yarn run lint
149+
```
150+
151+
9. **Show the user** the added or moved entries and explain what was done.
152+
153+
### For Beta to Non-Beta Version Release
154+
155+
When releasing from beta to a stable version (e.g., v16.1.0-beta.3 → v16.1.0):
156+
157+
1. **Remove all beta version labels** from the changelog:
158+
159+
- Change `### [v16.1.0-beta.1]`, `### [v16.1.0-beta.2]`, etc. to a single `### [v16.1.0]` section
160+
- Combine all beta entries into the stable release section
161+
162+
2. **Consolidate duplicate entries**:
163+
164+
- If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
165+
- Remove redundant changelog entries for fixes to beta features
166+
- Keep the most recent/accurate description of each change
167+
168+
3. **Update version diff links** using `bundle exec rake update_changelog`
169+
170+
### For New Beta Version Release
171+
172+
When creating a new beta version, ask the user which approach to take:
173+
174+
**Option 1: Process changes since last beta**
175+
176+
- Only add entries for commits since the previous beta version
177+
- Maintains detailed history of what changed in each beta
178+
179+
**Option 2: Collapse all prior betas into current beta**
180+
181+
- Combine all beta changelog entries into the new beta version
182+
- Removes previous beta version sections
183+
- Cleaner changelog with less version noise
184+
185+
After the user chooses, proceed with that approach.
186+
187+
## Examples
188+
189+
Run this command to see real formatting examples from the codebase:
190+
191+
```bash
192+
grep -A 3 "^#### " CHANGELOG.md | head -30
193+
```
194+
195+
### Good Entry Example
196+
197+
```markdown
198+
- **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).
199+
```
200+
201+
### Entry with Sub-bullets Example
202+
203+
```markdown
204+
- **Server Bundle Security**: Added new configuration options for enhanced server bundle security and organization:
205+
- `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)
206+
- `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)
207+
```
208+
209+
### Breaking Change Example
210+
211+
```markdown
212+
- **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:
213+
- `getOrWaitForComponent()`
214+
- `getOrWaitForStore()`
215+
- `getOrWaitForStoreGenerator()`
216+
- `reactOnRailsStoreLoaded()`
217+
- `streamServerRenderedReactComponent()`
218+
- `serverRenderRSCReactComponent()`
219+
220+
**Migration Guide:**
221+
222+
To migrate to React on Rails Pro:
223+
224+
1. Install the Pro package:
225+
yarn add react-on-rails-pro
226+
227+
2. Update your imports from `react-on-rails` to `react-on-rails-pro`:
228+
// Before
229+
import ReactOnRails from 'react-on-rails';
230+
231+
// After
232+
import ReactOnRails from 'react-on-rails-pro';
233+
```
234+
235+
## Additional Notes
236+
237+
- Keep descriptions concise but informative
238+
- Focus on the "what" and "why", not the "how"
239+
- Use past tense for the description
240+
- Be consistent with existing formatting in the changelog
241+
- Always ensure the file ends with a trailing newline
242+
- See CHANGELOG.md lines 15-18 for additional contributor guidelines

‎CLAUDE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,15 @@ Git hooks will automatically run linting on **all changed files (staged + unstag
4141
- **⚠️ MANDATORY BEFORE GIT PUSH**: `bundle exec rubocop` and fix ALL violations + ensure trailing newlines
4242
- Never run `npm` commands, only equivalent Yarn Classic ones
4343

44+
## Changelog
45+
46+
- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
47+
- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
48+
- **Format**: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
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
51+
- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples
52+
4453
## ⚠️ FORMATTING RULES
4554

4655
**Prettier is the SOLE authority for formatting non-Ruby files, and RuboCop for formatting Ruby files. NEVER manually format code.**

0 commit comments

Comments
 (0)