shakacode · AbanoubGhadban · Sep 24, 2025 · Sep 24, 2025 · Sep 24, 2025 · Sep 24, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,17 @@
 # Tips for Contributors
 
+**🏗️ Important: Monorepo Merger in Progress**
+
+We are currently working on merging the `react_on_rails` and `react_on_rails_pro` repositories into a unified monorepo. This will provide better development experience while maintaining separate package identities and licensing. See [docs/MONOREPO_MERGER_PLAN_REF.md](./docs/MONOREPO_MERGER_PLAN_REF.md) for details.
+
+During this transition:
+
+- Continue contributing to the current structure
+- License compliance remains critical - ensure no Pro code enters MIT-licensed areas
+- Major structural changes may be coordinated with the merger plan
+
+---
+
 - [docs/contributor-info/Releasing](./docs/contributor-info/releasing.md) for instructions on releasing.
 - [docs/contributor-info/pull-requests](./docs/contributor-info/pull-requests.md)
 - See other docs in [docs/contributor-info](./docs/contributor-info)

diff --git a/docs/DIRECTORY_LICENSING.md b/docs/DIRECTORY_LICENSING.md
@@ -0,0 +1,135 @@
+# Directory Licensing Documentation
+
+This document outlines the current and post-merger directory licensing structure for React on Rails projects.
+
+## Current Structure (Pre-Merger)
+
+### react_on_rails Repository - MIT Licensed
+
+All directories in the `react_on_rails` repository are MIT licensed:
+
+```
+react_on_rails/
+├── lib/react_on_rails/           # Core Ruby code (MIT)
+├── node_package/src/             # Core JS/TS code (MIT)
+│   └── pro/                      # Pro features placeholder (MIT but references pro)
+├── spec/                         # Core tests (MIT)
+├── docs/                         # Documentation (MIT)
+├── .github/                      # GitHub workflows (MIT)
+└── [all other directories]       # MIT
+```
+
+**Exception:** The `node_package/src/pro/` directory contains placeholder code that references Pro features, but the actual Pro implementation is in the separate `react_on_rails_pro` repository.
+
+### react_on_rails_pro Repository - Pro Licensed
+
+All directories in the `react_on_rails_pro` repository are Pro licensed:
+
+```
+react_on_rails_pro/
+├── lib/react_on_rails_pro/       # Pro Ruby code
+├── packages/node-renderer/       # Pro Node.js renderer
+├── spec/                         # Pro tests
+├── .circleci/                    # CircleCI config
+└── [all other directories]       # Pro licensed
+```
+
+## Post-Merger Structure (Target)
+
+After the monorepo merger, the unified repository will have clear directory-based licensing:
+
+### MIT Licensed Directories
+
+```
+react_on_rails/ (monorepo root)
+├── lib/react_on_rails/           # Core Ruby code
+├── packages/react-on-rails/      # Core NPM package
+├── spec/ruby/react_on_rails/     # Core Ruby tests
+├── spec/packages/react-on-rails/ # Core JS tests
+├── docs/                         # Shared documentation
+├── tools/                        # Shared development tools
+├── .github/                      # Unified GitHub workflows
+└── [shared config files]         # Build configs, etc.
+```
+
+### Pro Licensed Directories
+
+```
+react_on_rails/ (monorepo root)
+├── lib/react_on_rails_pro/       # Pro Ruby code
+├── packages/react-on-rails-pro/  # Pro NPM package
+├── packages/react-on-rails-pro-node-renderer/  # Pro Node renderer
+├── spec/ruby/react_on_rails_pro/ # Pro Ruby tests
+├── spec/packages/react-on-rails-pro/  # Pro JS tests
+└── spec/packages/react-on-rails-pro-node-renderer/  # Pro Node renderer tests
+```
+
+## License Compliance Rules
+
+### File-Level Compliance
+
+1. **Repository-Level Licensing**: Files inherit their license from the directory they're located in
+2. **No Mixed Directories**: Each directory is either entirely MIT or entirely Pro - no mixed licensing within a directory
+3. **Clear Boundaries**: The `LICENSE.md` file explicitly lists which directories fall under which license
+
+### Package-Level Compliance
+
+1. **Gemspec Files**:
+
+   - `react_on_rails.gemspec`: `s.license = "MIT"`
+   - `react_on_rails_pro.gemspec`: `s.license = "UNLICENSED"`
+
+2. **Package.json Files**:
+   - `packages/react-on-rails/package.json`: `"license": "MIT"`
+   - `packages/react-on-rails-pro/package.json`: `"license": "UNLICENSED"`
+   - `packages/react-on-rails-pro-node-renderer/package.json`: `"license": "UNLICENSED"`
+
+### Critical Compliance Points
+
+1. **Never Move Pro Code to MIT Directories**: During the merger, strict verification ensures no Pro-licensed code accidentally ends up in MIT-licensed directories
+
+2. **Update LICENSE.md Immediately**: Whenever directories are moved or created, `LICENSE.md` must be updated to reflect the new structure
+
+3. **Automated Verification**: CI checks will verify:
+   - All Pro directories are listed in LICENSE.md
+   - Package.json and gemspec files have correct license fields
+   - No orphaned or unlisted directories exist
+
+## Migration Phases and License Updates
+
+The monorepo merger plan includes specific license compliance checkpoints at each phase:
+
+- **Phase 1**: Update license references and documentation
+- **Phase 2**: Establish dual CI with clear directory boundaries
+- **Phase 3-4**: Reorganize directories while maintaining license compliance
+- **Phase 5-6**: Finalize structure and add automated license checking
+- **Phase 7**: Complete documentation and verification
+
+Each phase includes mandatory license compliance verification before proceeding to the next phase.
+
+## Developer Guidelines
+
+### When Adding New Files
+
+1. Determine if the functionality is Core (MIT) or Pro (subscription required)
+2. Place the file in the appropriate licensed directory
+3. Ensure the package.json or gemspec correctly reflects the license
+4. Update LICENSE.md if creating new directories
+
+### When Moving Files
+
+1. Verify the destination directory has the correct license for the file content
+2. Never move Pro features to MIT directories
+3. Update import statements and references
+4. Verify no licensing boundaries are crossed inappropriately
+
+### When Contributing
+
+1. Core features (MIT): Open for all contributors
+2. Pro features: Contributions become part of Pro offering
+3. Shared tooling/docs (MIT): Benefits both packages
+4. License compliance: Never compromise on proper licensing
+
+---
+
+_This document is maintained as part of the React on Rails monorepo merger plan. For implementation details, see [MONOREPO_MERGER_PLAN_REF.md](./MONOREPO_MERGER_PLAN_REF.md)_
diff --git a/docs/LICENSING_FAQ.md b/docs/LICENSING_FAQ.md
@@ -0,0 +1,126 @@
+# React on Rails Licensing FAQ
+
+## Post-Monorepo Merger Licensing
+
+### Q: What will happen to licensing after the monorepo merger?
+
+**A:** Nothing changes for end users! We'll maintain the same dual licensing structure:
+
+- **MIT Licensed (Free & Open Source):**
+
+  - `react_on_rails` Ruby gem
+  - `react-on-rails` NPM package
+  - Core functionality remains completely free
+
+- **Pro Licensed (Subscription Required for Production):**
+  - `react_on_rails_pro` Ruby gem
+  - `react-on-rails-pro` NPM package
+  - `react-on-rails-pro-node-renderer` NPM package
+  - Advanced features require valid subscription
+
+### Q: Will package installation or usage change?
+
+**A:** Yes. The Pro packages will become public instead of private. If you need Pro features, you will need to install the `react-on-rails-pro` NPM package in addition to `react-on-rails`, and import Pro features from `react-on-rails-pro`.
+
+### Q: How will the monorepo structure maintain license separation?
+
+**A:** The monorepo will have clear directory-based license boundaries:
+
+```
+react_on_rails/ (monorepo root)
+├── lib/
+│   ├── react_on_rails/           # MIT Licensed
+│   └── react_on_rails_pro/       # Pro Licensed
+├── packages/
+│   ├── react-on-rails/           # MIT Licensed
+│   ├── react-on-rails-pro/       # Pro Licensed
+│   └── react-on-rails-pro-node-renderer/  # Pro Licensed
+└── LICENSE.md                    # Documents which directories use which license
+```
+
+### Q: What about contributing to the project?
+
+**A:** Contributors should be aware of license boundaries:
+
+- **MIT areas:** Anyone can contribute freely
+- **Pro areas:** Contributions require agreement that improvements become part of the Pro offering
+- **License compliance:** Never move Pro code into MIT-licensed directories
+
+### Q: Will there be automated license compliance checking?
+
+**A:** Yes! The monorepo will include automated checks to ensure:
+
+- Pro files have proper license headers
+- Pro code never accidentally enters MIT-licensed directories
+- LICENSE.md accurately reflects all directory classifications
+- CI fails if license compliance is violated
+
+### Q: What if I'm currently using both packages?
+
+**A:** Perfect! The monorepo makes this easier:
+
+- Unified development and testing
+- Coordinated releases when needed
+- Shared tooling and documentation
+- Same separate billing and licensing as today
+
+### Q: Will documentation change?
+
+**A:** Documentation will be enhanced:
+
+- Combined docs show both free and pro features clearly
+- Examples will be properly labeled by license
+- Installation guides remain the same
+- License boundaries clearly documented
+
+### Q: When will this happen?
+
+**A:** The merger is planned as a 7-phase process. Each phase maintains full functionality and CI compliance. See [MONOREPO_MERGER_PLAN_REF.md](./MONOREPO_MERGER_PLAN_REF.md) for details.
+
+### Q: What if something goes wrong during the merger?
+
+**A:** Each phase has:
+
+- Complete rollback procedures
+- Clear success criteria
+- CI verification before proceeding
+- Community feedback integration
+- Immediate issue resolution process
+
+---
+
+## Current Licensing (Pre-Merger)
+
+### Q: How does licensing work today?
+
+**A:** We maintain two separate repositories:
+
+- **react_on_rails** (MIT) - Core functionality, completely free except pro directories as stated in LICENSE.md
+- **react_on_rails_pro** (Pro License) - Advanced features, subscription required for production
+
+### Q: What requires a Pro subscription?
+
+**A:** Pro features include:
+
+- Server-side rendering optimizations
+- Advanced caching strategies
+- React Server Components support
+- Node.js rendering process management
+- Premium support and consultation
+
+See [REACT-ON-RAILS-PRO-LICENSE.md](../REACT-ON-RAILS-PRO-LICENSE.md) for complete Pro license terms.
+
+### Q: Can I try Pro features for free?
+
+**A:** Yes! Pro license allows free use for:
+
+- Educational/classroom use
+- Personal hobby projects
+- Tutorials and demonstrations
+- Non-production evaluation
+
+Production use requires a valid subscription.
+
+---
+
+_For more information about the monorepo merger, see [MONOREPO_MERGER_PLAN_REF.md](./MONOREPO_MERGER_PLAN_REF.md)_
diff --git a/docs/MONOREPO_MERGER_PLAN.md b/docs/MONOREPO_MERGER_PLAN.md
@@ -1,7 +1,7 @@
 # React on Rails Monorepo Merger Plan
 
 **Version:** 1.0
-**Date:** 2025-01-24
+**Date:** 2025-09-24
 **Status:** Planning Phase
 **GitHub Issue:** [#1765](https://github.com/shakacode/react_on_rails/issues/1765)
 

diff --git a/docs/MONOREPO_MERGER_PLAN_REF.md b/docs/MONOREPO_MERGER_PLAN_REF.md
@@ -0,0 +1,16 @@
+# React on Rails Monorepo Merger Plan Reference
+
+The complete React on Rails Monorepo Merger Plan is located at:
+
+**[docs/MONOREPO_MERGER_PLAN.md](./MONOREPO_MERGER_PLAN.md)**
+
+This plan outlines the 7-phase implementation for merging the `react_on_rails` and `react_on_rails_pro` repositories into a unified monorepo while maintaining:
+
+- Separate package identities (2 Ruby gems + 3 NPM packages)
+- Proper license compliance (MIT vs Pro)
+- Complete git history preservation
+- CI integrity at every step
+
+**Status:** Phase 1 - License Cleanup & Documentation (In Progress)
+
+For implementation details, progress tracking, and specific tasks, refer to the main plan document.