Add changelog guidelines to CLAUDE.md

[justin808]

Summary

Following the approach from React on Rails PR #1867, this adds comprehensive changelog documentation requirements to the cypress-on-rails project.

Changes

• Created .claude/commands/update-changelog.md: Detailed guide for managing changelog entries with:

  • User-visible changes only policy (features, bug fixes, breaking changes, deprecations, performance improvements, security fixes)
  • Exclusion of linting fixes, code formatting, internal refactoring, test updates, documentation fixes, CI/CD changes
  • Formatting rules: Bold descriptions, PR links without hash symbols, author links
  • Category organization using standard and custom headings
  • Version management guidance for regular updates, beta releases, and beta-to-stable transitions
  • Real-world examples of properly formatted entries

• Created CLAUDE.md: Project-specific guidance for Claude Code including:

  • Critical requirements for commits/pushes
  • Development commands and workflow
  • Changelog section with quick reference to the detailed guidelines
  • Project architecture overview
  • Important notes about Cypress/Playwright integration

Adaptations for cypress-on-rails

This project differs from React on Rails in a few ways, so the content was adapted:

• Removed RuboCop references (this project doesn't use RuboCop)
• Updated repository URLs to shakacode/cypress-on-rails
• Simplified linting requirements to match this project's setup
• Adjusted examples to be relevant to Cypress/Playwright testing framework

Impact

This ensures consistent, high-quality changelog maintenance across the project, making it easier for users to understand what changes affect them. Contributors will have clear guidance on:

• What changes warrant changelog entries
• How to format entries consistently
• How to handle version management and releases

🤖 Generated with Claude Code

[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 21 minutes and 22 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 d1662ca and 1abce55.

📒 Files selected for processing (2)

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch justin808/changelog-guidelines

---

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]

PR Review: Add changelog guidelines to CLAUDE.md

Summary

This PR adds comprehensive documentation for Claude Code to help maintain consistent changelog entries and provides project-specific guidance. This is a valuable addition that will improve developer experience and changelog quality.

Code Quality & Best Practices

✅ Strengths

1. Well-structured documentation: Both files are clear, comprehensive, and well-organized
2. Trailing newlines: Both files correctly end with newline characters (critical requirement)
3. Practical examples: The update-changelog.md includes real-world examples and formatting guidance
4. Version management: References the existing update_changelog rake task (confirmed in rakelib/update_changelog.rake)
5. Comprehensive coverage: Addresses multiple scenarios (regular updates, beta releases, migrations)

⚠️ Issues Found

1. List Marker Inconsistency (Medium Priority)

File: .claude/commands/update-changelog.md

The documentation specifies using dashes (-) for list items:

- **Bold description of change**. [PR 1818]...

However, the actual CHANGELOG.md uses asterisks (*):

* **VCR middleware (use_cassette)**: optional middleware...
* **Rails 8 example app & CI job**...

Recommendation: Update all examples in update-changelog.md to use * instead of - to match the existing changelog format.

Locations to fix:

• Line 32 (example format)
• Line 50 (breaking changes format)
• Line 189-198 (all examples)

2. PR Link Format Inconsistency (Medium Priority)

File: .claude/commands/update-changelog.md and CLAUDE.md

The documentation states "NO hash symbol" and shows [PR 123] format, but the actual changelog uses both formats:

• [PR 167] - most entries use this
• [#201] - the most recent Unreleased entry uses this

Evidence from CHANGELOG.md:

* **BREAKING: Generator folder structure**: ... [#201]
* **VCR middleware**: ... [PR 167]
* **Rails 8 example app**: ... [PR 174]

Recommendation:

• Clarify that BOTH formats are acceptable (preferred: [PR 123], acceptable: [#123])
• OR establish one format as the standard going forward
• The current "no hash symbol" rule contradicts the actual changelog

Locations to fix:

• update-changelog.md line 40: Update the "NO hash symbol" statement
• CLAUDE.md line 27: Update format specification

3. Author Attribution Inconsistency (Low Priority)

File: .claude/commands/update-changelog.md

The documentation shows author links as required:

by [username](https://github.com/username)

However, many changelog entries don't include author attribution:

* **Rails 8 example app & CI job**... [PR 174]  # No author
* Fix update `index.js`... [PR 147] by [Judahmeek]  # Has author

Recommendation: Clarify that author attribution is optional or provide guidance on when to include it (e.g., "include for external contributors").

4. Minor: RuboCop Reference (Low Priority)

File: CLAUDE.md line 54

States: - **Linting**: RuboCop for Ruby

However, RuboCop is not in the gemspec dependencies or Gemfile. The PR description mentions this was supposed to be removed:

"Removed RuboCop references (this project doesn't use RuboCop)"

Recommendation: Remove line 54 or update to reflect actual linting tools used (if any).

Security Concerns

✅ None identified. This is documentation-only.

Performance Considerations

✅ N/A - Documentation files have no runtime performance impact.

Test Coverage

✅ N/A - Documentation files don't require tests.

However, I recommend:

• Verifying the /update-changelog slash command works correctly with these instructions
• Testing the documented workflows manually to ensure accuracy

Additional Suggestions

5. Git Branch Reference

File: update-changelog.md lines 111-112

References master branch, but the repository may use main. Consider using a variable or checking what the actual default branch name is.

6. Command Examples Could Use Actual Project Data

The examples in update-changelog.md reference generic scenarios. Consider adding a note pointing to actual changelog entries as examples:

# See actual examples in CHANGELOG.md lines 88-99 for proper formatting

Verdict

Overall Assessment: Good PR with valuable documentation, but needs corrections for accuracy.

Required Changes:

1. ✋ Fix list marker from - to * throughout examples
2. ✋ Clarify PR link format policy (both formats or choose one)
3. ⚠️ Remove RuboCop reference from CLAUDE.md

Optional Improvements:
4. 💡 Clarify author attribution is optional
5. 💡 Verify master/main branch naming
6. 💡 Add cross-references to actual changelog examples

Once the required changes are addressed, this will be an excellent addition to the project! The comprehensive guidance will significantly improve changelog maintenance consistency.

---

Review generated by Claude Code