Document RBS type signatures for contributors

[justin808]

Summary

Add comprehensive documentation about RBS type signatures to help contributors understand and use type checking.

Changes

• Created docs/contributor-info/rbs-type-signatures.md with detailed RBS documentation
• Added reference to RBS docs in CONTRIBUTING.md
• Removed previous top-level README section (per PR feedback)

Documentation Includes

• Benefits of RBS type signatures (better autocomplete, early error detection, improved documentation, refactoring safety)
• IDE support information (Steep, Solargraph, RubyMine, VS Code)
• Usage instructions for validation and listing type files
• File structure and location information
• Contributing guidelines for adding new signatures
• Compatibility requirements and resources

Context

React on Rails includes comprehensive RBS type signatures (added in PR #1945), but this feature wasn't documented for contributors. This documentation is now properly positioned in the contributor-info directory.

Testing

• Verified formatting with Prettier (all checks pass)
• Confirmed all pre-commit hooks pass
• Verified sig/README.md exists and contains detailed RBS documentation
• Confirmed rake tasks exist (rbs:validate, rbs:list)

Fixes #1953

🤖 Generated with Claude Code

---

This change is 

[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 0 minutes and 17 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 9404439 and 02a9b25.

📒 Files selected for processing (2)

• CONTRIBUTING.md (1 hunks)
• docs/contributor-info/rbs-type-signatures.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/rbs-docs

---

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]

Pull Request Review - PR #1998

✅ Summary

This PR adds comprehensive documentation for RBS type signature support to the README. The addition is well-structured, informative, and addresses issue #1953 effectively.

---

🎯 Strengths

1. Excellent Content Quality

• Clear, well-organized section with logical flow (Benefits → IDE Support → Usage → Location → Compatibility)
• Practical examples with both rake tasks and direct RBS CLI commands
• Appropriate use of emojis (🔍) consistent with README style
• Good balance between high-level benefits and practical implementation details

2. Accurate Technical Details

• ✅ Verified: sig/README.md exists with comprehensive RBS documentation
• ✅ Verified: Rake tasks rbs:validate and rbs:list exist in rakelib/rbs.rake
• ✅ Verified: RBS signatures exist (10 .rbs files with ~268 lines of type definitions)
• ✅ Verified: PR Add RBS type signatures for improved type safety #1945 was merged and added the RBS signatures
• Compatibility info is accurate (Ruby >= 3.0 includes RBS)

3. Good Placement

• Positioned right after "Prerequisites" section, making it easy to discover
• Before "Get Help & Support", which is logical as it's a feature documentation
• Follows the established pattern of feature documentation in the README

4. Proper Testing

• Author verified Prettier formatting compliance
• Pre-commit hooks passed
• All referenced files and tasks verified to exist

---

💡 Suggestions for Improvement

1. Minor: RBS Gem Dependency Clarification

The documentation states "RBS gem >= 2.0" under Compatibility, but I notice the gemspec doesn't explicitly include RBS as a dependency. This is correct since RBS is bundled with Ruby 3.0+, but it might be worth clarifying:

Suggested addition to the Compatibility section:

## Compatibility

- Ruby >= 3.0 (RBS is included in Ruby 3.0+)
- RBS gem >= 2.0 (bundled with Ruby 3.0+, or install separately for older versions)

2. Optional: Add "See it in action" callout

Consider adding a small note encouraging developers to try it in their IDE:

## Usage

Type signatures work automatically once you configure your IDE. Try typing `ReactOnRails.` in your code editor to see autocomplete suggestions!

### Validation
...

3. Optional: Link to IDE Setup Guides

For Solargraph and Ruby LSP, developers might benefit from setup instructions. Consider adding:

- VS Code - Via [Ruby LSP extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) or [Solargraph extension](https://marketplace.visualstudio.com/items?itemName=castwide.solargraph)

---

🔒 Security, Performance & Test Coverage

• ✅ Security: No security concerns - documentation only change
• ✅ Performance: No performance impact - documentation only change
• ✅ Tests: Not applicable - documentation change. The rake tasks are already functional

---

📋 Code Quality & Best Practices

• ✅ Follows project's documentation style and formatting conventions
• ✅ Uses consistent markdown formatting with proper heading hierarchy
• ✅ Code examples use proper bash syntax highlighting
• ✅ All internal references verified (sig/README.md, rake tasks)
• ✅ All external links point to authoritative sources
• ✅ No trailing whitespace or formatting issues expected

---

✨ Changelog Compliance

Per CLAUDE.md guidelines, this change:

• ✅ Should be in CHANGELOG: Yes - this is a user-visible documentation improvement
• Format should be: [PR 1998](https://github.com/shakacode/react_on_rails/pull/1998) by [justin808](https://github.com/justin808): Document RBS type signature support in README

---

🎉 Final Verdict

LGTM (Looks Good To Me) - Approve with minor optional suggestions.

This is a solid documentation addition that makes an existing feature more discoverable. The content is accurate, well-structured, and properly researched. The minor suggestions above are optional enhancements that could improve clarity but are not blockers.

Great work addressing issue #1953! This will definitely help developers leverage the RBS type signatures that were added in PR #1945.

---

Review checklist:

• ✅ Code quality and best practices
• ✅ Potential bugs or issues (none found)
• ✅ Performance considerations (not applicable)
• ✅ Security concerns (none)
• ✅ Test coverage (not applicable for docs)
• ✅ CLAUDE.md style compliance
• ✅ All references verified

[claude]

Code Review - PR #1998

Overview

This PR adds documentation for RBS type signatures to the main README. The documentation is well-structured and addresses the issue raised in #1953.

---

✅ Strengths

1. Clear Structure: The new section follows a logical flow (benefits → IDE support → usage → location → compatibility)
2. Accurate Information: Verified that:
   • sig/README.md exists with detailed RBS documentation
   • rakelib/rbs.rake provides the documented rake tasks (rbs:validate, rbs:list)
   • RBS files are properly organized in sig/react_on_rails/ directory (10 .rbs files found)
3. Helpful Links: Includes references to official RBS documentation and internal sig/README.md
4. Complete Coverage: Addresses all points mentioned in issue Document RBS type signature support in README #1953

---

📝 Suggestions for Improvement

1. Section Placement

The new "Type Safety (RBS)" section is placed immediately after the Prerequisites section and before "Get Help & Support". Consider:

• Moving it after "Why React on Rails?" (line ~131) to keep it closer to feature-oriented content
• Or placing it in a more prominent position in the "What's New" or "About" sections since this is a significant feature

Current structure:

• Prerequisites
• → Type Safety (RBS) ← New section here
• Get Help & Support

Suggested structure:

• Prerequisites
• Get Help & Support
• Contributing
• → Type Safety (RBS) ← Better placement near technical content
• Work with Us

2. Ruby Version Compatibility

The PR states "Ruby >= 3.0 (RBS is included in Ruby 3.0+)" but the project's minimum supported Ruby is 3.2 (per CLAUDE.md:63 and README Prerequisites). Consider:

• Changing to "Ruby >= 3.2" to match project requirements
• Or clarifying: "Ruby >= 3.2 (React on Rails requirement; RBS included since Ruby 3.0)"

3. Missing Rake Task

The documentation mentions bundle exec rake rbs:validate and bundle exec rake rbs:list but doesn't mention rake rbs:steep or rake rbs:all which exist in rakelib/rbs.rake. Consider adding a section about type checking with Steep:

### Type Checking with Steep

To run the Steep static type checker:

bundle exec rake rbs:steep
# Or run both validation and type checking
bundle exec rake rbs:all

4. Minor: Command Consistency

The PR uses two command formats:

• bundle exec rake rbs:validate (uses bundle exec with rake)
• bundle exec rbs -I sig validate (direct RBS CLI)

Both are correct, but for consistency with the codebase convention (per CLAUDE.md which emphasizes rake tasks), consider leading with the rake commands.

---

🔍 Code Quality Assessment

• Formatting: ✅ Markdown formatting appears correct
• Links: ✅ All links are valid (sig/README.md exists, RBS GitHub is correct)
• Accuracy: ✅ All commands and features mentioned exist and work
• Testing: ✅ Author verified with Prettier and pre-commit hooks

---

🎯 Priority Recommendations

1. High Priority: Update Ruby version requirement from 3.0 to 3.2
2. Medium Priority: Consider section placement for better discoverability
3. Nice to Have: Mention rake rbs:steep and rake rbs:all tasks

---

✅ Approval Status

The PR is functionally correct and ready to merge with minor improvements. The documentation accurately reflects the codebase state and will help users discover and use RBS type signatures. The suggestions above are quality-of-life improvements, not blockers.

Recommendation: Approve with optional improvements for future iteration.

---

Great work documenting this feature! 🎉

[claude]

PR Review: Document RBS Type Signatures for Contributors

Overall Assessment

Excellent work! This PR successfully addresses issue #1953 by documenting RBS type signature support for contributors. The documentation is well-structured, comprehensive, and properly positioned in the contributor documentation.

---

Strengths

1. Well-Structured Documentation

• Clear hierarchy with benefits, IDE support, usage, and contributing sections
• Practical examples with actual commands developers will use
• Good balance between high-level overview and technical details

2. Proper Placement

• Correctly placed in docs/contributor-info/ rather than top-level README
• Follows the repository's documentation organization pattern
• Appropriately linked from CONTRIBUTING.md

3. Accurate Content

• All rake tasks referenced (rbs:validate, rbs:list) are verified to exist in rakelib/rbs.rake
• File structure mirrors actual sig/ directory layout
• Commands are tested and functional

4. Consistent with Repository Standards

• Follows existing documentation style (see pull-requests.md, releasing.md)
• Uses relative links appropriately (../../sig/README.md)
• Adheres to markdown formatting standards

---

Code Quality & Best Practices

Documentation Quality

• Clear section headings and logical flow
• Actionable instructions for contributors
• Helpful examples and resources
• Cross-references to existing documentation (sig/README.md)

Completeness

• Covers all essential topics: benefits, IDE support, validation, contributing
• Links to external resources (RBS docs, Steep, Solargraph)
• Includes compatibility requirements

---

Suggestions for Enhancement

1. Minor: Add Example of Type Error Detection

Consider adding a brief example showing what an RBS validation error looks like to help contributors understand what they're looking for.

2. Optional: Link to IDE Setup Guides

If there are specific setup instructions for popular Ruby IDEs, consider linking to them or creating a quick-start guide.

3. Consider: Version of RBS in Project

The documentation mentions RBS gem >= 2.0, but doesn't specify what version the project currently uses. This might be helpful for contributors.

---

Security Concerns

None identified. This is documentation-only changes with no code execution or security implications.

---

Performance Considerations

N/A - Documentation changes have no runtime performance impact.

---

Test Coverage

Verification Performed

• Verified sig/README.md exists and contains complementary documentation
• Confirmed rake tasks exist in rakelib/rbs.rake (rbs:validate, rbs:list)
• Verified sig/ directory structure matches documentation
• Confirmed 14 RBS files exist in sig/react_on_rails/

Documentation Testing

• All relative links are valid
• Command examples are accurate
• Referenced files and directories exist

---

Adherence to CLAUDE.md Guidelines

Formatting

• Prettier will handle markdown formatting
• No manual formatting conflicts expected

Changelog

• Documentation-only change - no CHANGELOG entry required per guidelines
• Correctly omitted (Do NOT add entries for: documentation fixes)

Contribution Standards

• Follows existing documentation patterns
• Properly cross-referenced
• Maintains consistency with contributor docs

---

Issue Resolution

Fixes #1953

• Addresses all points in the original issue
• Provides comprehensive RBS documentation
• Positioned for contributor audience (not end users)
• Includes all suggested content plus additional helpful sections

---

Final Recommendation

APPROVE - This PR is ready to merge.

The documentation is high-quality, accurate, well-positioned, and provides exactly what contributors need to understand and work with RBS type signatures in the project. The minor suggestions above are optional enhancements, not blockers.

Great work on improving the contributor experience!