Add changelog guidelines to CLAUDE.md

[justin808]

Summary

Following React on Rails PR #1867, this adds comprehensive changelog documentation requirements to the package_json project.

Changes

• New file: .claude/commands/update-changelog.md - Detailed guide (227 lines) for updating CHANGELOG.md, including:

  • Critical requirements for what changes should/shouldn't be documented
  • Formatting rules with PR and author links
  • Category organization (Added, Changed, Fixed, etc.)
  • Process instructions for regular updates, beta releases, and version management
  • Real examples and anti-patterns

• New file: CLAUDE.md - Development guide (77 lines) covering:

  • Critical requirements for linting and formatting
  • Essential development commands
  • Changelog section with quick reference
  • Project architecture overview
  • Formatting rules

Key Features

Changelog Guidelines:

• Focus on user-visible changes only (features, bug fixes, breaking changes, deprecations, performance improvements, security fixes)
• Exclude internal changes (linting, formatting, refactoring, tests, documentation fixes, CI/CD)
• Standardized format: [PR 123](https://github.com/shakacode/package_json/pull/123) by [username](https://github.com/username)
• Consistent with keepachangelog.com standards

Developer Experience:

• Clear documentation on when to update the changelog
• /update-changelog command for guided updates
• Examples drawn from the codebase itself
• Version management via rake task

Impact

This ensures consistent, high-quality changelog maintenance across the project, making it easier for:

• Users to understand what changes affect them
• Contributors to know when and how to document changes
• Maintainers to manage releases with complete changelogs

Comparison with React on Rails

This implementation adapts the React on Rails changelog guidelines for the package_json project by:

• Updating repository URLs and project-specific references
• Simplifying to relevant package managers (no yarn/webpack-specific details)
• Keeping core principles: user-visible changes, standardized formatting, clear categorization
• Maintaining the same high standards for changelog quality

🤖 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 14 minutes and 6 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 d32d6fa and 7704168.

📒 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/add-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

Overview

This PR adds comprehensive documentation for changelog management and development guidelines. The changes are well-structured and provide valuable guidance for contributors.

Strengths ✅

1. Clear Documentation Structure: Both files are well-organized with clear sections and hierarchies
2. Comprehensive Coverage: Excellent coverage of changelog requirements, formatting rules, and development workflows
3. Practical Examples: Good use of examples and command references for developers
4. Consistency: Follows the same approach as the React on Rails project, maintaining consistency across Shakacode projects
5. User-Focused: Correctly emphasizes user-visible changes only, which keeps changelogs meaningful

Code Quality Issues 🔍

Critical Issues

None found - this is purely documentation.

Minor Issues & Suggestions

1. CLAUDE.md Line 33 - Version Management Task Reference

- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers (if task exists)

Issue: The "(if task exists)" qualifier creates uncertainty.
Suggestion: Either confirm the task exists and remove the qualifier, or provide alternative instructions if it doesn't exist yet.

2. update-changelog.md Line 82 - Rake Task Reference

bundle exec rake update_changelog

Issue: Same as above - this task is referenced but may not exist.
Recommendation:

• If the task doesn't exist yet, consider creating it or documenting manual steps
• If it does exist, remove the qualifier from CLAUDE.md

3. CLAUDE.md Line 34 - Example Command May Fail

- **Examples**: Run `grep -A 3 "^#### " CHANGELOG.md | head -30` to see real formatting examples

Potential Issue: This command assumes changelog entries exist. Since CHANGELOG.md currently only has:

## [Unreleased]

## [0.1.0] - 2023-09-15

- Initial release

The grep command will return no results (no "####" headers exist yet).
Suggestion: Either add a note that this will be useful once entries are added, or provide a different example.

4. update-changelog.md - Git Log Commands
Multiple references to git log commands are excellent, but consider adding a note about:

• What to do if no tags exist yet (current state of the repo)
• Handling the first changelog entries after 0.1.0

Testing & Validation 🧪

Documentation files are not executable code, but consider:

1. Testing the example commands to ensure they work
2. Verifying the bundle exec rake update_changelog task exists or creating it
3. Walking through the changelog update process manually to validate the instructions

Security Considerations 🔒

No security concerns - these are documentation files only.

Performance Considerations ⚡

Not applicable for documentation.

Test Coverage 📊

Not applicable - documentation doesn't require tests. However, the instructions themselves serve as a test specification for the changelog update process.

Best Practices & Suggestions 💡

1. Consider adding a troubleshooting section to update-changelog.md for common issues:

   • What to do when git tags are out of sync
   • How to handle merge conflicts in CHANGELOG.md
   • What to do if PR numbers aren't in commit messages

2. Add validation checklist at the end of update-changelog.md:

   • File ends with newline
   • No duplicate section headers
   • All PR links use correct format (no hash)
   • All entries have author links
   • RuboCop passes

3. Document the /update-changelog command - CLAUDE.md references it but doesn't explain how it works or where it's defined (though it's clear from the file structure).

4. Consider adding examples from the actual project once real changelog entries are made - this will make the documentation more concrete.

Recommendations Summary

Must Fix (Blocking):

• None

Should Fix (Before Merge):

• Clarify whether bundle exec rake update_changelog task exists, or create it
• Update the example command in CLAUDE.md to handle the current sparse changelog state

Nice to Have (Future):

• Add troubleshooting section
• Add validation checklist
• Update examples once real changelog entries exist

Conclusion

LGTM with minor suggestions ✅

This is excellent documentation that will significantly improve the contributor experience. The minor issues noted above are suggestions for improvement rather than blockers. The PR can be merged as-is, with the recommendations addressed in follow-up work if desired.

The documentation is thorough, well-structured, and will serve as a valuable reference for both AI assistants and human contributors.

---

Review generated by Claude Code