Add upgrade guide for v16.0.x to v16.1.1

docs/upgrading/release-notes/16.1.0.md

@@ -0,0 +1,159 @@
+# React on Rails 16.1.x Release Notes
+
+## Upgrading from 16.0.x to 16.1.x
+
+Update your gem and npm package versions:
+
+```ruby
+# Gemfile
+gem "react_on_rails", "16.1.1"
+gem "shakapacker", "8.2.0"
+```
+
+```json
+// package.json
+{
+  "dependencies": {
+    "react-on-rails": "16.1.1",
+    "shakapacker": "8.2.0"
+  }
+}
+```
+
+Then run `bundle install` and your package manager's install command.
+
+**Important:** The shakapacker gem and npm package versions must match exactly.
+
+## Version Compatibility
+
+| Component   | Minimum | Recommended |
+| ----------- | ------- | ----------- |
+| Ruby        | 3.0     | 3.3+        |
+| Node.js     | 18      | 22+         |
+| Shakapacker | 6.0     | 8.2.0+      |
+| React       | 18      | 18+         |
+| Rails       | 5.2     | 7.0+        |
+
+**Note:** CI tests against Ruby 3.2+ and Node.js 20+, but the gem supports lower versions as shown above.
+
+## New Features in v16.1.0
+
+### Doctor Rake Task
+
+New diagnostic command for troubleshooting setup issues:
+
+```bash
+rake react_on_rails:doctor
+VERBOSE=true rake react_on_rails:doctor  # For detailed output
+```
+
+### Server Bundle Security
+
+New configuration options for enhanced server bundle security:
+
+```ruby
+# config/initializers/react_on_rails.rb
+ReactOnRails.configure do |config|
+  # Directory for server bundle output (default: "ssr-generated")
+  config.server_bundle_output_path = "ssr-generated"
+
+  # When enabled, server bundles only load from private directories
+  config.enforce_private_server_bundles = true
+end
+```
+
+### Enhanced bin/dev Script
+
+The updated `bin/dev` script provides better development server management with support for multiple modes:
+
+- `bin/dev` - Default HMR mode with webpack-dev-server
+- `bin/dev static` - Watch mode without HMR
+- `bin/dev prod` - Development with production-optimized assets
+
+### Multiple Procfile Support
+
+Three Procfile configurations for different development scenarios:
+
+1. **Procfile.dev** (HMR mode) - Rails server + webpack dev server for client + webpack watch for server bundle
+2. **Procfile.dev-static-assets** (Static watch mode) - Rails server + webpack watch mode
+3. **Procfile.dev-prod-assets** (Production assets in development) - Rails server with production-optimized assets
+
+### Webpack Configuration Updates
+
+- New `generateWebpackConfigs.js` helper for better configuration management
+- Improved babel.config.js setup
+
+### Generator Improvements
+
+**Note:** These improvements only affect newly generated code from `rails g react_on_rails:install` or component generators. Existing applications are unaffected.
+
+- Modern TypeScript patterns with better type inference
+- Optimized tsconfig.json with `"moduleResolution": "bundler"`
+- Enhanced Redux TypeScript integration
+- Smart `bin/dev` defaults that auto-navigate to `/hello_world` route
+
+## Security Enhancements
+
+v16.1.0 includes important security improvements:
+
+- **Command injection protection**: Fixed command injection vulnerabilities in generator package installation commands by replacing unsafe string interpolation with secure array-based system calls ([PR 1786](https://github.com/shakacode/react_on_rails/pull/1786)) by [justin808](https://github.com/justin808)
+- **Improved input validation**: Enhanced package manager validation and argument sanitization across all generators ([PR 1786](https://github.com/shakacode/react_on_rails/pull/1786)) by [justin808](https://github.com/justin808)
+- **Hardened DOM selectors**: Using `CSS.escape()` and proper JavaScript escaping for XSS protection ([PR 1791](https://github.com/shakacode/react_on_rails/pull/1791)) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+
+## Bug Fixes
+
+### v16.1.1
+
+- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)) by [AbanoubGhadban](https://github.com/AbanoubGhadban)
+
+### v16.1.0
+
+- Fixed LoadError in `rake react_on_rails:doctor` when using packaged gem ([PR 1795](https://github.com/shakacode/react_on_rails/pull/1795)) by [justin808](https://github.com/justin808)
+- Fixed packs generator error when `server_bundle_js_file` is empty ([PR 1802](https://github.com/shakacode/react_on_rails/pull/1802)) by [justin808](https://github.com/justin808)
+- Fixed NoMethodError in environments without Shakapacker ([PR 1806](https://github.com/shakacode/react_on_rails/pull/1806)) by [justin808](https://github.com/justin808)
+- Fixed inconsistent Shakapacker version requirements ([PR 1806](https://github.com/shakacode/react_on_rails/pull/1806)) by [justin808](https://github.com/justin808)
+
+## Deprecations
+
+Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`.
+
+## Common Upgrade Issues
+
+### Shakapacker Version Mismatch
+
+**Symptom:** Assets fail to compile or inconsistent behavior between development and production.
+
+**Solution:** Ensure your Shakapacker gem and npm package versions match exactly:
+
+```bash
+# Check gem version
+bundle show shakapacker
+
+# Check npm version
+npm list shakapacker
+# or
+yarn list shakapacker
+```
+
+Both should show the same version (e.g., 8.2.0).
+
+### Missing Server Bundle After Upgrade
+
+**Symptom:** Server-side rendering fails with "bundle not found" errors.
+
+**Solution:** If you're using `server_bundle_output_path`, ensure the directory exists and your build process outputs to that location. Run `rake react_on_rails:doctor` to diagnose configuration issues.
+
+## Pro License Features
+
+v16.1.0 introduced foundational changes for React on Rails Pro, including:
+
+- Core/Pro separation with clear licensing boundaries
+- Runtime license validation with graceful fallback
+- Enhanced immediate hydration (Pro-only feature)
+
+These changes are internal and do not affect open-source users. For information about Pro features like streaming SSR, React Server Components, and enhanced performance optimizations, see [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).
+
+## Related Resources
+
+- [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md)
+- [Configuration Reference](../../api-reference/configuration.md)

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

@@ -21,7 +21,13 @@ rails generate react_on_rails:install
 - `shakapacker.yml` settings
 - other configuration files
 
-## Upgrading to v16
+## Upgrading to v16.1.x (from v16.0.x)
+
+This is a minor release - update your gem and npm package versions, then run `bundle install` and your package manager's install command. See the [v16.1.x Release Notes](release-notes/16.1.0.md) for new features and bug fixes.
+
+**Deprecation:** Remove `config.generated_assets_dirs` from your configuration if present. Asset paths are now automatically determined from `public_output_path` in `config/shakapacker.yml`.
+
+## Upgrading to v16 (from v14/v15)
 
 ### Breaking Changes