Add changelog guidelines to CLAUDE.md

[justin808]

Summary

Following Shakapacker PR #742, this adds comprehensive changelog documentation requirements to CLAUDE.md.

Changes

• Changelog section added with clear guidelines on when to update CHANGELOG.md
• User-visible changes only: Features, bug fixes, breaking changes, deprecations, performance improvements
• Excluded from changelog: Linting fixes, code formatting, internal refactoring, test updates, documentation fixes
• Format requirements:
  • Always link to the PR: [PR #123](https://github.com/shakacode/react_on_rails/pull/123)
  • Always link to the author: by [username](https://github.com/username)
  • Keep formatting consistent with existing entries
  • Update version diff links when releasing
  • Bold formatting for breaking changes with migration guide links

Impact

This ensures consistent, high-quality changelog maintenance across the project, making it easier for users to understand what changes affect them.

Comparison with Shakapacker

Reviewed other Shakapacker settings and confirmed that:

• Both projects already have similar critical requirements
• React on Rails has more comprehensive formatting rules
• The main missing piece was the changelog guidelines (now added)
• Git hooks are already properly configured in both projects

🤖 Generated with Claude Code

---

This change is 

Summary by CodeRabbit

• Documentation
  • Added a comprehensive CHANGELOG section to contributor docs with guidance on what to include/exclude in release notes, standardized section headers and example entry formats, PR/author linking and release process conventions, and formatting rules (prettier/rubocop) to ensure consistent changelog entries.

[coderabbitai]

Warning

Rate limit exceeded

@justin808 has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 13 minutes and 47 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 3ead148 and 80b707b.

📒 Files selected for processing (2)

• .claude/commands/update-changelog.md (1 hunks)
• CLAUDE.md (1 hunks)

Walkthrough

Added a comprehensive "Changelog" section to CLAUDE.md with contributor guidelines, changelog format rules, examples, and formatting/tooling conventions; expanded documentation content covering workflow, formatting, and release/versioning guidance.

Changes

Cohort / File(s)	Summary
Documentation: CLAUDE.md CLAUDE.md	Added a Changelog section with user-visible change criteria, standard and custom section headers, PR/author link format, release/version process, example entries, and formatting rules (Prettier for non-Ruby, RuboCop for Ruby). Expanded workflow and contributor guidance content.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Check clarity and correctness of changelog section headings and example entries
• Verify PR/author link formatting examples and release/version instructions
• Ensure formatting/tooling guidance (Prettier vs RuboCop) is consistent with project standards

Possibly related PRs

• Update instructions to agents on formatting #1794: Overlapping edits to CLAUDE.md and contributor formatting/conflict-resolution guidance.
• Update changelog and fix CI formatting issues #1796: Updates .prettierignore and CHANGELOG.md; touches same documentation/changelog files.

Suggested reviewers

• AbanoubGhadban
• alexeyr-ci2

Poem

🐇 I hopped through lines of changelog cheer,
New headers, links, and rules appear,
A tidy log where changes bloom —
Developers dance, and bugs meet doom! 🎉

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "Add changelog guidelines to CLAUDE.md" directly and clearly describes the main change in the changeset. According to the provided context, the PR adds a dedicated Changelog section to CLAUDE.md with comprehensive guidelines for when and how to update the CHANGELOG.md file. The title is concise (37 characters), specific (mentions both what was added and where), and uses clear language without noise, emojis, or vague terminology. A teammate reviewing the git history would immediately understand that this PR adds changelog documentation guidelines to the project's guidelines file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code Review - PR 1867

This is a well-crafted documentation addition that addresses an important gap in contributor guidelines.

Code Quality & Best Practices - EXCELLENT

Strengths:

• Perfectly aligned with existing CHANGELOG.md format (verified against actual changelog entries)
• Clear categorization between user-visible and non-user-visible changes
• Consistent with project style and warning/emphasis patterns in CLAUDE.md
• Logical placement between Development Commands and Formatting Rules sections
• Actionable guidance with concrete examples

The prescribed format matches actual CHANGELOG.md entries perfectly for PR links, author attribution, and breaking changes formatting.

Potential Issues - NONE

The changes are documentation-only with no code execution.

Performance & Security - N/A

Documentation changes have no runtime performance impact and no security concerns.

Test Coverage - Not Applicable

Documentation changes don't require tests. The examples can be manually verified against existing changelog entries.

Minor Enhancement Suggestions (Optional)

1. Consider cross-referencing the keepachangelog.com guidance mentioned in CHANGELOG.md line 17
2. Could mention the update_changelog rake task in the version diff links bullet point
3. Clarify the version diff links bullet to include rake task info

What I Really Like

1. Prevents changelog noise - The exclusion list keeps focus on user value
2. Bold breaking changes requirement - Critical for users scanning upgrade impacts
3. Consistent with Shakapacker PR 742 - Creates consistency across ShakaCode projects
4. Attribution enforcement - Proper credit to contributors built into guidelines

Verdict - LGTM! ✅

This will improve changelog quality and reduce cognitive load for contributors.

No blockers identified. Ready to merge.

---

Review by Claude Code - Comprehensive analysis with format validation against existing changelog entries

[claude]

Code Review: Add changelog guidelines to CLAUDE.md

✅ Overall Assessment

This is a well-structured PR that adds important changelog documentation guidelines to CLAUDE.md. The changes are clear, concise, and align well with the project's existing practices.

---

📋 Code Quality & Best Practices

Strengths:

• Clear structure: The new section follows the existing CLAUDE.md organization pattern
• Actionable guidelines: Provides specific, actionable rules rather than vague suggestions
• Good categorization: Clear distinction between what should and shouldn't be in the changelog
• Consistent placement: Logically placed after "Development Commands" section, before "Formatting Rules"

Suggestions for improvement:

1. PR link format inconsistency: The guidelines show [PR #123] but examining CHANGELOG.md reveals actual usage is inconsistent:

   • Line 28: [PR #1857] (with hash)
   • Line 80: [PR 1818] (without hash)
   • Line 88+: [PR 1798] (without hash in most cases)

   Recommendation: Update the guideline to match the most common pattern in CHANGELOG.md, which appears to be [PR 1818] (without the hash symbol). This would be:

   - Always link to the PR: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)`

2. Version diff links clarification: The guideline mentions "update the version diff links at the bottom of CHANGELOG.md" but doesn't reference the existing automation. CHANGELOG.md line 18 states: "After a release, please make sure to run bundle exec rake update_changelog". Consider adding a reference to this rake task for consistency.

---

🐛 Potential Issues

Minor Issues Found:

1. Missing newline at end of file: Per CLAUDE.md:749b7e1dc:4 "ALWAYS ensure files end with a newline character". The diff doesn't show if the file ends with a newline. Please verify this critical requirement is met.

2. Format validation: The guidelines should mention that the format must be compatible with bundle exec rake update_changelog task. This ensures the guidelines align with the automated tooling.

---

🎯 Consistency with Existing Practices

Verified against CHANGELOG.md:

✅ Correctly documented:

• User-visible vs. internal changes distinction (matches CHANGELOG.md practice)
• PR and author linking format (mostly correct, see note above about hash symbol)
• Bold formatting for breaking changes (matches line 32-74 in CHANGELOG.md)

⚠️ Needs verification:

• Section headers: CHANGELOG.md uses specific headers like "Added", "Breaking Changes", "Bug Fixes", "New Features", "Deprecations". Consider adding this to the guidelines to help contributors place their entries correctly.

---

🚀 Performance Considerations

N/A - Documentation-only change with no performance impact.

---

🔒 Security Concerns

None - This is a documentation change that improves project quality and consistency.

---

🧪 Test Coverage

Not applicable - This is a documentation change. However, I recommend:

1. After merging, test the guidelines by creating a sample changelog entry following these new rules
2. Ensure bundle exec rake update_changelog still works correctly with entries following this format

---

📝 Additional Recommendations

1. Add section header guidance: Include a note about which section header to use (Added, Fixed, Changed, Deprecated, Removed, Security) to match keepachangelog.com format referenced in CHANGELOG.md:17

2. Example entry: Consider adding a complete example entry to make the format crystal clear:

   - **Feature Name**: Brief description of the change. [PR 1234](https://github.com/shakacode/react_on_rails/pull/1234) by [username](https://github.com/username)

3. Cross-reference: Add a reference to CHANGELOG.md:17-18 which mentions keepachangelog.com and the update_changelog rake task

4. Consistency check: Run through recent CHANGELOG.md entries to ensure all examples in the guidelines match actual usage patterns

---

✨ Summary

This PR adds valuable documentation that will improve changelog quality and consistency. With minor adjustments for format consistency (especially the PR link format) and ensuring the trailing newline requirement is met, this will be ready to merge.

Action Items Before Merge:

1. ✅ Verify file ends with newline character (CRITICAL per CLAUDE.md)
2. ⚠️ Consider adjusting PR link format from [PR #123] to [PR 123] to match most common usage
3. 💡 Optional: Add section header guidance (Added, Fixed, Changed, etc.)
4. 💡 Optional: Add reference to bundle exec rake update_changelog task

Great work on improving project documentation! 🎉

---

Review generated following CLAUDE.md guidelines

[claude]

PR Review: Add changelog guidelines to CLAUDE.md

Summary

This PR adds comprehensive changelog documentation requirements to CLAUDE.md. Overall, this is a high-quality addition that will improve consistency and maintainability of the changelog. The guidelines are clear, well-structured, and align well with the existing changelog format.

---

✅ Strengths

1. Excellent Clarity: The guidelines clearly distinguish between user-visible and non-user-visible changes with concrete examples
2. Format Consistency: The format requirements match the existing changelog patterns perfectly (verified against CHANGELOG.md)
3. Proper Placement: Logically positioned after "Essential Commands" section and before "FORMATTING RULES"
4. Comprehensive Coverage: Addresses PR linking, author attribution, version diff updates, and breaking change formatting
5. Consistent with Existing Patterns: All example formats match actual changelog entries (e.g., [PR #1857], by [username](https://github.com/username))

---

🔍 Observations & Minor Suggestions

1. Inconsistency in PR Link Format

The existing CHANGELOG.md shows two formats in use:

• [PR #1857](...) (with hashtag) - line 28
• [PR 1818](...) (without hashtag) - line 80

Recommendation: Consider specifying which format is preferred or update the guideline to mention both are acceptable. The format [PR #123] is clearer and more common in GitHub contexts.

2. Missing "Changed" and "Removed" Categories

The guidelines mention "new features, bug fixes, breaking changes, deprecations, performance improvements" but the CHANGELOG.md also uses sections like:

• #### Breaking Changes (line 30)
• #### Bug Fixes (line 78)
• #### New Features (line 84)
• #### Security Enhancements (line 123)
• #### Internal Improvements (line 130)

Suggestion: Consider adding a brief note about using the standard Keep a Changelog categories (Added, Changed, Deprecated, Removed, Fixed, Security) since line 17 of CHANGELOG.md references this standard.

3. Minor Wording Enhancement

Current text:

- When releasing a version, update the version diff links at the bottom of CHANGELOG.md

Suggested improvement:

- When releasing a version, update the version diff links at the bottom of CHANGELOG.md (or use `bundle exec rake update_changelog` as noted in CHANGELOG.md line 18)

This creates better cross-reference with existing documentation.

---

🛡️ Code Quality Assessment

• Documentation Quality: Excellent
• Consistency: High (matches existing patterns)
• Completeness: Very good (covers all essential aspects)
• Maintainability: High (easy to understand and follow)

---

🔒 Security Considerations

No security concerns. This is documentation-only change.

---

🧪 Test Coverage

N/A - Documentation change only. No code changes requiring tests.

---

📊 Performance Considerations

N/A - Documentation change only.

---

🎯 Potential Issues

None identified. This is a clean, well-written documentation addition.

---

✨ Final Recommendation

Approve with minor optional enhancements.

The PR is ready to merge as-is. The suggestions above are optional refinements that could improve clarity but are not blockers. This addition will significantly help maintain changelog quality and consistency across the project.

Great work aligning this with the Shakapacker PR #742 approach! 👍

[claude]

Code Review: Add changelog guidelines to CLAUDE.md

Overall Assessment

✅ LGTM - This is a solid addition that will improve changelog consistency and quality. The guidelines are clear, well-structured, and align with existing practices in the CHANGELOG.md file.

---

Strengths

1. Clear User-Visible Focus: The distinction between user-visible and internal changes is excellent. This prevents changelog bloat and keeps it relevant for users.

2. Comprehensive Format Requirements: The formatting guidelines match the existing CHANGELOG.md patterns perfectly:

   • PR links with proper format ✓
   • Author attribution ✓
   • Breaking changes formatting ✓

3. Good Placement: Located right after the Development Commands section, making it easy to find before commits.

4. Consistent with Project Standards: Aligns with the existing pull request template and contributor documentation.

---

Minor Observations and Suggestions

1. Trailing Newline Check ⚠️

CRITICAL per project requirements: Ensure the modified CLAUDE.md file ends with a newline character. The CLAUDE.md file itself states: ALWAYS ensure files end with a newline character. Please verify this before merging.

2. Consistency with CHANGELOG.md Header

The CHANGELOG.md file already has contributor instructions. Consider mentioning bundle exec rake update_changelog in the CLAUDE.md guidelines as well, since it is important for version diff link updates.

3. Examples Could Be More Specific

The guideline says Keep formatting consistent with existing entries but could benefit from a concrete example showing the complete format with PR link and author attribution together.

4. Section Categories

The actual CHANGELOG.md uses specific section headings like Added, Breaking Changes, Bug Fixes, Deprecations, Security Enhancements, API Improvements. Suggestion: Mention that contributors should use appropriate section headings under the Unreleased version.

5. Migration Guide Link Pattern

Looking at actual examples in CHANGELOG.md, the migration guides can be inline in the changelog itself or in separate docs. Consider clarifying that migration guides can be inline for smaller changes or in separate docs for major version upgrades.

---

Code Quality

• ✅ Clear and concise writing
• ✅ Uses markdown formatting effectively
• ✅ No spelling or grammar issues
• ✅ Consistent with existing CLAUDE.md style

Best Practices

• ✅ Follows the principle of write it down for future contributors
• ✅ Reduces cognitive load by providing clear examples
• ✅ Prevents common mistakes

Performance Considerations

• ✅ N/A - This is documentation only

Security Concerns

• ✅ None - Documentation change only

Test Coverage

• ✅ N/A - No tests needed for documentation
• ⚠️ However, consider if you want to add a CI check that validates CHANGELOG.md entries follow the format. This could be a future enhancement.

---

Final Recommendation

Approve with minor verification:

1. ✅ Must do: Verify CLAUDE.md ends with a newline character
2. 💡 Nice to have: Consider adding the suggestions above in a follow-up PR

This is a valuable addition that will help maintain changelog quality. The guidelines are clear, actionable, and well-aligned with existing practices.

---

Note: I verified the guidelines against actual CHANGELOG.md entries and confirmed the format matches existing patterns. Great attention to detail!

[claude]

PR Review: Add changelog guidelines to CLAUDE.md

Overall Assessment

This is a well-crafted PR that adds valuable documentation to improve changelog consistency. The guidelines are clear, comprehensive, and align well with the project's existing documentation standards.

Strengths

1. Clear Categorization: The distinction between user-visible and non-user-visible changes is well-defined
2. Concrete Examples: Specifies exactly what should and should not be in the changelog
3. Format Requirements: Provides specific formatting rules with examples
4. Consistency: The style matches the existing CLAUDE.md structure
5. Strategic Placement: Logically placed after Development Commands

Suggestions for Improvement

1. Add Concrete Example

Consider adding an example entry to make the format crystal clear, such as:

• Fixed memory leak in server rendering pool. PR #1234 by username

2. Clarify Version Diff Links

The guideline mentions updating version diff links at the bottom of CHANGELOG.md. Consider clarifying what these are (the [Unreleased] and version comparison URLs) for new contributors.

3. Cross-reference Existing Guidelines

The CHANGELOG.md already references keepachangelog.com. Consider adding a note to see existing CHANGELOG.md entries for examples and follow the keepachangelog.com format.

Code Quality Checklist

• Formatting: Markdown is properly formatted ✅
• Consistency: Style matches existing conventions ✅
• Completeness: Covers when to add and not add entries ✅
• No Breaking Changes: Pure documentation addition ✅

Security and Performance

• No security concerns (documentation-only) ✅
• No performance impact (documentation-only) ✅

Verification

I checked CHANGELOG.md and confirmed:

• The PR link format matches existing entries
• The author link format matches existing entries
• Bold formatting is used for breaking changes
• Version diff links exist at the bottom

Final Recommendation

APPROVE with minor suggestions ✅

The PR is ready to merge as-is. The suggestions above are optional enhancements that would make the guidelines even more helpful for new contributors, but they do not block approval.

Great work ensuring consistency across ShakaCode projects!