Update instructions to agents on formatting

[justin808]

This change is 

Summary by CodeRabbit

• Documentation

  • Updated contributor guides with strict Prettier-only formatting rules, an explicit merge/rebase conflict-resolution workflow, and clarified upgrade-status output examples.
  • Expanded development and test commands in CLAUDE.md, plus added environment/setup guidance.
  • Linters guide now documents Prettier usage, autofix commands, and the rationale to avoid manual formatting.

• Chores

  • Updated .gitignore to exclude local Claude Code settings (.claude/settings.local.json).

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Documentation updates establish Prettier as the sole formatting authority, add explicit workflows for standard development and merge-conflict resolution, and expand developer commands. A new ignore rule is added for Claude Code local settings. Sections are renamed and renumbered in contributor guides, with updated examples for upgrade status output.

Changes

Cohort / File(s)	Summary
Contributor docs: formatting and workflows docs/contributor-info/coding-agents-guide.md, docs/contributor-info/linters.md, CLAUDE.md	Centralize Prettier-only formatting policy; add standard and conflict-resolution workflows; prohibit manual formatting; expand setup and testing commands; reorganize sections/numbering; add example output commands for upgrade status.
Repo config .gitignore	Add ignore rule for .claude/settings.local.json with a labeled section and spacing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• alexeyr-ci
• AbanoubGhadban

Poem

hop hop! I lint, I leap—
Prettier’s the shepherd, whitespace sheep.
No manual trims, no conflict fright,
autofix hums through day and night.
In docs I burrow clear and neat,
.gitignore keeps my burrow discreet.
carrot-merge complete! 🥕✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title Check	⚠️ Warning	The title "Only formatting changes to docs" is misleading because the raw summaries show removal of example code blocks and explicit commands in multiple documentation sections (for example, Emergency Procedures and Rollback), which are substantive content edits rather than purely cosmetic formatting, and the PR objectives describe guidance updates for React on Rails v16. Therefore the title does not accurately summarize the main changes and may understate the impact of the edits. This fails the clarity and accuracy requirement for a PR title.	Please update the PR title to reflect the substantive documentation changes (e.g., "Docs: update coding agents guide and React on Rails v16 upgrade instructions" or "Docs: refine coding agents guidance and remove outdated example commands"), or confirm and document that only formatting was applied if that is truly the case; also ensure the PR description matches the actual changes. After the title and description are corrected, re-run the title check to confirm accuracy.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 82b1a1a and 34e412b.

📒 Files selected for processing (4)

• .gitignore (1 hunks)
• CLAUDE.md (2 hunks)
• docs/contributor-info/coding-agents-guide.md (2 hunks)
• docs/contributor-info/linters.md (1 hunks)

---

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 for PR #1794: Update documentation for v16 and coding agents

Thank you for updating the documentation! I've reviewed the changes and have the following feedback:

✅ Strengths

• Clean formatting improvements with consistent markdown table syntax
• Removal of unnecessary empty lines improves readability
• Consistent code block formatting throughout the documentation

📝 Observations & Suggestions

1. Markdown Table Formatting

The table header separator change in coding-agents-guide.md and troubleshooting-build-errors.md is good:

-| -------------- | ----------- | ------- | ------- | ---- |
+|----------------|-------------|---------|---------|------|

This provides cleaner, more consistent formatting.

2. Code Block Consistency

Good improvements in JavaScript code blocks, particularly the standardization of quotes and semicolons:

new webpack.ProvidePlugin({
  Routes: "$app/utils/routes"
})

3. Documentation Structure

Excellent removal of redundant blank lines after headers like "Detection:" and "Auto-fix:" - this creates tighter, more readable documentation.

⚠️ Potential Issues

1. Missing Newline at End of Files

Per your CLAUDE.md requirements, please verify all modified files end with a newline character. This is a CI requirement.

2. Consider Running Full Lint Check

Before merging, ensure you've run:

bundle exec rubocop
rake lint

🔍 Security & Performance

• No security concerns identified - changes are documentation-only
• No performance implications

✅ Test Coverage

• Documentation changes don't require test updates
• Changes maintain accuracy of technical content

💡 Additional Suggestions

1. Consider adding a note in the version compatibility matrices about which versions are LTS/recommended for new projects
2. The js-routes troubleshooting section is much clearer now - great work simplifying the explanations

✨ Summary

This is a solid documentation update that improves readability and maintains technical accuracy. The changes align well with the project's documentation standards. Once you verify the trailing newlines requirement, this should be ready to merge.

Great work on making the documentation more accessible for both developers and coding agents! 👍

---

Review generated following react_on_rails CLAUDE.md guidelines

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/contributor-info/coding-agents-guide.md (1)

108-112: Fix: sed corrupts Gemfile quoting — use Bundler or a safer sed
The sed replacement will produce mismatched quotes (e.g. gem 'react_on_rails", "~> 16.0'); replace with either:

- sed -i 's/react_on_rails.*~> 14\.0/react_on_rails", "~> 16.0/' Gemfile
+ bundle add react_on_rails --version="~> 16.0" --strict

- sed -i 's/react_on_rails.*~> 14\.0/react_on_rails", "~> 16.0/' Gemfile
+ sed -i -E "s/(gem ['\"]react_on_rails['\"], )['\"~><=^ 0-9.]+/\1'~> 16.0'/" Gemfile

🧹 Nitpick comments (8)

docs/javascript/troubleshooting-build-errors.md (2)

56-59: Map default export in ProvidePlugin (ESM correctness).

If app/javascript/utils/routes.js exports export default Routes, ProvidePlugin should reference the default export to avoid injecting the module namespace. Recommend:

- new webpack.ProvidePlugin({
-   Routes: "$app/utils/routes"
- })
+ new webpack.ProvidePlugin({
+   Routes: ["$app/utils/routes", "default"]
+ })

---

64-68: Mirror the ESM fix in the “remove if not using js-routes” example.

Keep the example consistent with the default‑export mapping so users don’t copy a mismatched pattern elsewhere.

- new webpack.ProvidePlugin({
-   Routes: "$app/utils/routes"  // ← Remove this
- })
+ new webpack.ProvidePlugin({
+   Routes: ["$app/utils/routes", "default"]  // ← Remove this
+ })

docs/contributor-info/coding-agents-guide.md (6)

81-82: Fix prerequisite check: verify Gemfile contents, not filename.

ls Gemfile | grep -q shakapacker always succeeds if the file exists. Use grep on file content:

- ls Gemfile | grep -q shakapacker || echo "⚠️  Shakapacker required"
+ grep -q "shakapacker" Gemfile || echo "⚠️  Shakapacker required"

---

141-143: Add Ruby version check to the pre‑upgrade checklist.

You already check Node; add Ruby to ensure compatibility with the v16 matrix.

 echo "Node.js version: $(node --version)"
+echo "Ruby version: $(ruby -v)"

---

24-31: Call out CSS Modules import pattern (project‑specific gotcha).

Given the project’s CSS Modules config with namedExports: true, add a reminder that imports should use import * as style from './file.module.css' to avoid runtime/classname issues. Consider adding a bullet here or in Best Practices.

---

102-123: Optional: prefer Bundler flow over manual sed during upgrades.

Since you already recommend bundle add elsewhere, keep upgrade steps consistent and less error‑prone:

- # 1. Update versions
- sed -i 's/react_on_rails.*~> 14\.0/react_on_rails", "~> 16.0/' Gemfile
- sed -i 's/"react-on-rails": "^14\./"react-on-rails": "^16./' package.json
+ # 1. Update versions
+ bundle add react_on_rails --version="~> 16.0" --strict
+ npm pkg set dependencies.react-on-rails="^16.0.0"

---

306-356: Include upgrade‑specific path note: app‑react16 files move to app/.

Agents frequently miss that app-react16/* files are copied/moved to /app/* during conversion, affecting import paths. Add a one‑liner in Best Practices or Upgrade Workflows to re‑verify relative imports after the move.

---

221-235: Tighten detection regex for ProvidePlugin alias errors.

Anchoring on $app is good; also consider matching both alias and file path to reduce false positives:

-/Error: Can't resolve.*\$app/
+/Error: Can't resolve.*(\$app|utils\/routes)/

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dcca723 and 82b1a1a.

📒 Files selected for processing (3)

• docs/contributor-info/coding-agents-guide.md (1 hunks)
• docs/guides/upgrading-react-on-rails.md (0 hunks)
• docs/javascript/troubleshooting-build-errors.md (2 hunks)

💤 Files with no reviewable changes (1)

• docs/guides/upgrading-react-on-rails.md

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-09-16T08:01:11.146Z

Learnt from: justin808
PR: shakacode/react_on_rails#1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.

Applied to files:

• docs/javascript/troubleshooting-build-errors.md
• docs/contributor-info/coding-agents-guide.md

📚 Learning: 2025-04-26T21:55:55.874Z

Learnt from: alexeyr-ci2
PR: shakacode/react_on_rails#1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.

Applied to files:

• docs/javascript/troubleshooting-build-errors.md
• docs/contributor-info/coding-agents-guide.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: dummy-app-integration-tests (3.2, 20)
• GitHub Check: dummy-app-integration-tests (3.4, 22)
• GitHub Check: rspec-package-tests (3.2, minimum)
• GitHub Check: build
• GitHub Check: rspec-package-tests (3.2, latest)
• GitHub Check: rspec-package-tests (3.4, latest)
• GitHub Check: rspec-package-tests (3.4, minimum)

🔇 Additional comments (1)

docs/javascript/troubleshooting-build-errors.md (1)

150-159: Compatibility table formatting LGTM.

Header alignment is correct and improves readability. No content change needed.

[claude]

Pull Request Review: #1794 - Only formatting changes to docs

Summary

This PR appears to have no actual changes in the diff. The PR shows 0 additions and 0 deletions, with no files modified.

Issues Identified

1. Empty PR: The pull request contains no actual changes to review. This could be due to:
   • Changes being already merged to the base branch
   • The branch being accidentally reset
   • An incomplete push of intended changes

Recommendations

1. Verify Intended Changes: Please check if the formatting changes mentioned in the title were actually committed and pushed to the branch justin808-doc-updates-2025-09-17.

2. If changes are missing, you may need to:

   • Commit your local changes: git add . && git commit -m "Apply formatting changes to docs"
   • Push to the remote branch: git push origin justin808-doc-updates-2025-09-17

3. If this PR is no longer needed, consider closing it.

Next Steps

Please update the PR with the actual formatting changes so they can be properly reviewed. If you need help with git commands or have already made the changes locally but they're not showing up, let me know and I can assist.

---

Note: Unable to review code quality, performance, security, or test coverage as no changes are present in this PR.

[claude]

Pull Request Review: Documentation Updates

🔍 Current Status

This PR shows 0 additions and 0 deletions despite having 3 commits that describe documentation improvements:

1. Improvements for v16 and coding agents documentation
2. Clarifying js-routes as optional dependency
3. Formatting fixes after merge conflict resolution

⚠️ Primary Issue

The PR appears to be empty - no file changes are visible in the diff. This could indicate:

• The commits were already merged to the base branch through another PR
• The branch needs to be rebased against the current main branch
• There's an issue with how the PR was created or pushed

📋 Based on Commit Messages

The intended changes appear valuable:

• ✅ Documentation improvements for React on Rails v16
• ✅ Enhanced troubleshooting guides for build errors
• ✅ Clearer guidance for AI coding agents
• ✅ Proper clarification that js-routes is optional (not required)

🚀 Recommended Actions

1. Check branch status:

git checkout justin808-doc-updates-2025-09-17
git pull origin main
git status

2. If changes exist locally but not in PR:

git push --force-with-lease origin justin808-doc-updates-2025-09-17

3. If changes were already merged:

• Close this PR as the changes are already in main
• Reference the PR where these changes were actually merged

✅ Quality Checks (for when changes are visible)

Per CLAUDE.md requirements, before merging ensure:

• Run bundle exec rubocop with zero violations
• All files end with newline characters
• Run rake lint for full lint check

💡 Note

The commit messages suggest valuable documentation improvements. Once the actual changes are visible in the PR, I'd be happy to provide a detailed review of the content, formatting, and technical accuracy.

Please update the PR or clarify the status of these changes so we can proceed with a proper review.

---

Review generated following react_on_rails contribution guidelines

[claude]

Code Review for PR #1794: Only formatting changes to docs

Thank you for these documentation improvements! I've reviewed the changes and here's my feedback:

✅ Strengths

1. Critical formatting guidance: Excellent addition of Prettier-specific formatting rules in CLAUDE.md. The emphasis on letting Prettier handle ALL formatting is crucial for maintaining consistency.

2. Merge conflict resolution workflow: The detailed step-by-step workflow for handling formatting during merge conflicts is extremely valuable. This addresses a common pain point where manual formatting creates "formatting wars."

3. Consistent messaging: The formatting rules are properly duplicated across CLAUDE.md, coding-agents-guide.md, and linters.md, ensuring developers encounter this critical information regardless of their entry point.

4. Clear warnings: The use of ⚠️ CRITICAL markers effectively highlights the importance of these rules.

📋 Recommendations

1. Consider adding examples: While the documentation is clear, adding a brief example of what NOT to do (e.g., manually adjusting indentation) could help prevent common mistakes.

2. Git hooks mention: The CLAUDE.md mentions that "Git hooks are installed automatically during setup" - consider clarifying if these hooks also run Prettier or just RuboCop.

3. .gitignore addition: Good addition of .claude/settings.local.json. This prevents local Claude Code settings from being committed.

✅ Code Quality Assessment

• Best Practices: ✅ Documentation follows markdown best practices
• Consistency: ✅ Formatting rules are consistent across all modified files
• Clarity: ✅ Instructions are clear and actionable
• File Structure: ✅ All files properly end with newlines (as per project requirements)

🔒 Security & Performance

• No security concerns identified
• No performance implications (documentation only)

🧪 Test Coverage

Not applicable for documentation changes.

✅ Verdict

APPROVED - These are valuable documentation improvements that will help prevent common formatting issues and improve the developer experience. The emphasis on Prettier as the sole formatting authority is particularly important for maintaining consistency across the codebase.

The PR title accurately reflects that these are formatting-related documentation changes only, with no code modifications.

---

Reviewed according to project guidelines in CLAUDE.md

[claude]

Code Review for PR #1794: Only formatting changes to docs

✅ Overall Assessment

This PR successfully improves the documentation around formatting rules and Prettier usage, which is crucial for maintaining consistent code formatting across the project. The changes are well-structured and address important pain points.

🎯 Strengths

1. Clear formatting guidelines: The new FORMATTING RULES section in CLAUDE.md provides explicit, actionable instructions for handling code formatting
2. Merge conflict resolution workflow: The step-by-step guide for resolving conflicts without causing formatting wars is particularly valuable
3. Consistency across docs: The same formatting guidance is propagated to multiple documentation files, ensuring all contributors see the same instructions
4. Proper .gitignore addition: Adding '.claude/settings.local.json' to .gitignore prevents local Claude Code settings from being committed

📋 Suggestions for Improvement

1. Consider consolidating duplicate content

The formatting rules are now duplicated across three files (CLAUDE.md, coding-agents-guide.md, linters.md). Consider:

• Creating a single source of truth (perhaps in linters.md)
• Referencing it from other documents to avoid maintenance burden

2. Add examples for common scenarios

The merge conflict resolution workflow could benefit from a concrete example showing actual Git commands and file states.

3. Clarify Prettier configuration

Consider mentioning where the Prettier configuration lives (.prettierrc or package.json) and what file types it handles.

✔️ Code Quality

• Documentation is clear and well-structured
• Markdown formatting is consistent
• Instructions are actionable and specific

🔒 Security

No security concerns - this PR only modifies documentation and gitignore.

🚀 Performance

No performance impact - documentation only.

🧪 Test Coverage

Not applicable for documentation changes.

💡 Additional Notes

The emphasis on 'NEVER manually format' and letting Prettier be the 'SOLE authority' is excellent - this will prevent many common issues with formatting conflicts between developers and tools.

✨ Recommendation

APPROVE - This PR improves the developer experience by clarifying formatting rules and workflows. The changes are beneficial and ready to merge.

Great work on improving the project documentation! 🎉

[claude]

Pull Request Review: Update instructions to agents on formatting

Thank you for this PR that enhances the documentation for AI coding agents and formatting guidelines. Here's my comprehensive review:

✅ Strengths

1. Clear and Emphatic Formatting Guidelines: The addition of Prettier as the sole formatting authority is excellent. This will prevent formatting inconsistencies and conflicts between different tools.

2. Practical Merge Conflict Resolution Workflow: The step-by-step workflow for resolving merge conflicts while maintaining proper formatting is very valuable. The explicit warning against manual formatting during conflict resolution addresses a common pain point.

3. Consistent Messaging: The formatting rules are consistently emphasized across all modified files (CLAUDE.md, coding-agents-guide.md, and linters.md), ensuring the message reaches all relevant contexts.

4. Good .gitignore Addition: Adding .claude/settings.local.json to .gitignore is appropriate for excluding local Claude Code settings.

📝 Suggestions for Improvement

1. Title Accuracy: The PR title says 'Only formatting changes to docs' but this actually adds substantial new content about formatting rules. Consider updating the title to something like 'Add comprehensive formatting guidelines and Prettier documentation' to better reflect the changes.

2. Documentation Consistency: In CLAUDE.md, you have both:

   • Code Formatting: Format code with Prettier: rake autofix
   • Later: Run rake autofix or yarn start format

   Consider clarifying that rake autofix runs both Prettier AND linters, while yarn start format only runs Prettier.

3. Minor Formatting Observation: While the content is clear, some sections could benefit from consistent heading levels. For example, in linters.md, the new Prettier section uses ### for subsections while ESLint section doesn't have subsections.

🔍 Code Quality

• Documentation Quality: Clear, well-structured, and actionable
• Technical Accuracy: Commands and workflows appear correct
• Completeness: Covers common scenarios comprehensively

✅ Security & Performance

No security or performance concerns - these are documentation-only changes.

✅ Test Coverage

Not applicable for documentation changes.

💡 Additional Considerations

1. Consider adding a note about what rake autofix actually does (runs Prettier + ESLint fixes + RuboCop fixes) to help users understand why it's the preferred command.

2. The 'formatting wars' concept is well explained but could benefit from a brief example of what this looks like (e.g., 'ESLint adds semicolons, Prettier removes them, causing endless back-and-forth').

✅ Overall Assessment

This is a valuable PR that will significantly improve the developer experience, especially for those using AI coding assistants. The emphasis on automated formatting and clear workflows will help prevent common issues. I recommend approval with the minor suggestions above considered for future improvements.

The changes align well with the project's existing documentation style and provide practical, actionable guidance that will reduce friction in the development process.