Explore Two Top-Level Directories Structure

[justin808]

Summary

Explore a cleaner monorepo structure with two top-level product directories instead of the complex lib/ merging attempted in PR #2108.

Status: Experimental - let's see if this feels better

Background

PR #2108 attempted to merge lib/ directories and move Pro code to be a sibling of core code. This caused:

• Multiple test failures
• Complex path updates
• Confusion about structure

New Approach: Create two top-level directories, one for each product.

Proposed Structure

react_on_rails/ (monorepo root)
│
├── react_on_rails/                # Core product directory
│   ├── lib/react_on_rails/
│   ├── spec/
│   ├── react_on_rails.gemspec
│   └── README.md
│
├── react_on_rails_pro/            # Pro product directory
│   ├── lib/react_on_rails_pro/
│   ├── spec/
│   ├── react_on_rails_pro.gemspec
│   └── README.md
│
├── packages/                      # All NPM packages (shared workspace)
│   ├── react-on-rails/
│   ├── react-on-rails-pro/
│   └── react-on-rails-pro-node-renderer/
│
├── docs/                          # Shared documentation
├── .github/                       # Shared CI
├── package.json                   # Workspace manager
├── Gemfile                        # Both gems
└── LICENSE.md

Benefits

1. Crystal Clear Separation

• "Where's the core code?" → react_on_rails/
• "Where's the Pro code?" → react_on_rails_pro/
• No confusion about boundaries

2. Symmetric Structure

Both products have identical internal organization:

• lib/
• spec/
• <product>.gemspec
• README.md

3. Simpler Licensing

MIT Licensed: react_on_rails/, packages/react-on-rails/
Pro Licensed: react_on_rails_pro/, packages/react-on-rails-pro*/

4. Independent Evolution

Each product can have:

• Its own documentation
• Its own examples
• Its own configuration
• Its own development scripts

But share: CI, packages/, root tooling

5. Minimal Pro Changes

• Pro code STAYS mostly where it is (minimal breakage)
• Core code moves into subdirectory (predictable updates)
• NPM packages unchanged (Phase 5 already done)

Migration Steps

Step 1: Create Core Product Directory

# Create core directory
mkdir react_on_rails_temp

# Move core Ruby code
git mv lib/ react_on_rails_temp/
git mv spec/ react_on_rails_temp/
git mv react_on_rails.gemspec react_on_rails_temp/

# Rename
git mv react_on_rails_temp/ react_on_rails/

Step 2: Pro Stays Put

• react_on_rails_pro/ is already at top level
• Minimal or no changes needed
• Just verify it still works

Step 3: Update Configuration

• Update Gemfile: gemspec path: "react_on_rails"
• Update core gemspec paths (now in subdirectory)
• Update LICENSE.md paths
• Update CI workflow paths

Step 4: Test Everything

• Core gem builds
• Pro gem builds
• All specs pass
• NPM packages build
• CI passes

Testing Checklist

• Core gem builds: gem build react_on_rails/react_on_rails.gemspec
• Pro gem builds: gem build react_on_rails_pro/react_on_rails_pro.gemspec
• Core specs pass: cd react_on_rails && bundle exec rspec
• Pro specs pass: cd react_on_rails_pro && bundle exec rspec
• NPM packages build: yarn build
• All CI checks pass
• LICENSE.md accurate
• Documentation updated

Open Questions

1. Directory naming: Use react_on_rails/ or react_on_rails_core/?

   • Leaning toward react_on_rails/ (matches gem name)

2. Dummy apps: Each in their product directory?

   • Leaning toward yes (keeps everything together)

3. Shared tooling: Where should bin/ scripts live?

   • Could stay at root (shared)
   • Or each product has its own

Success Criteria

• Structure feels clearer than current
• Both gems build and install
• All tests pass
• CI configuration simpler
• License boundaries obvious
• Easy to explain to new contributors

Comparison to PR #2108

PR #2108 (Failed):

• Merged lib/ directories
• Moved Pro OUT of react_on_rails_pro/
• Complex path updates
• Many test failures

This Approach:

• TWO separate top-level directories
• Pro STAYS in react_on_rails_pro/
• Core moves into react_on_rails/
• Clearer separation

Implementation Plan

1. Create feature branch
2. Implement Step 1 (move core code)
3. Test core gem locally
4. Verify Pro still works
5. Update root configuration
6. Update CI
7. Create PR when local tests pass
8. Iterate based on feedback

Rollback Plan

If this also doesn't feel right:

• Revert to master (Phase 5 complete)
• Accept current structure as "good enough"
• Move on to other improvements

Goal: Find a structure that's clear and maintainable, not achieve some theoretical perfect organization.

Detailed Plan

See TWO_TOP_LEVEL_DIRS_PLAN.md for full implementation details.

Estimated Effort

• Optimistic: 1 day
• Realistic: 2-3 days
• Pessimistic: 4-5 days (if unexpected issues)

Related

• Closes Phase 6: Restructure Ruby Gems to Final Monorepo Layout #2103 (old Phase 6 approach - too complex)
• Closes Phase 6: Restructure Ruby Gems to Final Monorepo Layout #2108 (PR that failed with lib/ merging)
• Alternative to original MONOREPO_MERGER_PLAN.md Phase 6