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

[justin808]

Summary

Based on a recent upgrade from v16.0.1.rc.2 to v16.1.1, there are several important steps and improvements that should be documented to help users upgrade smoothly.

Suggested Documentation Additions

1. Upgrade Steps Section

Add a dedicated section for upgrading from v16.0.x to v16.1.1:

## Upgrading from 16.0.x to 16.1.1

### Step 1: Update Dependencies
Update both the gem and npm package versions:

**Gemfile:**
```ruby
gem "react_on_rails", "16.1.1"
gem "shakapacker", "8.2.0"  # Required for compatibility

package.json:

"shakapacker": "8.2.0"

Step 2: Bundle and Yarn Install

bundle update react_on_rails shakapacker
yarn install

Step 3: Run the Install Generator

Run the generator to get the latest improvements:

rails generate react_on_rails:install

Note: The generator will prompt to overwrite several files. Review each change carefully, especially if you have customizations.

### 2. Generator Improvements Documentation
Document the new features added by the v16.1.1 generator:

```markdown
## New Development Features in v16.1.1

### 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
   - Optional: Sidekiq, Redis, Mailcatcher configurations

### Webpack Configuration Updates
- New `generateWebpackConfigs.js` helper for better configuration management
- Updated configurations for better v16.1.1 compatibility
- Improved babel.config.js setup

3. Version Compatibility Matrix

Add or update the compatibility matrix:

| react_on_rails | shakapacker (gem) | shakapacker (npm) | Rails | Ruby  |
|----------------|-------------------|-------------------|-------|-------|
| 16.1.1         | 8.2.0            | 8.2.0             | 7.0+  | 3.0+  |
| 16.0.x         | 8.0.0            | 8.0.0             | 7.0+  | 3.0+  |

4. Breaking Changes / Important Notes

## Important Notes for v16.1.1

### Shakapacker Version Sync
**Critical:** The shakapacker gem and npm package versions MUST match exactly. The generator will fail if versions differ:
- Gem version in Gemfile.lock
- NPM version in package.json

### Bug Fixes in 16.1.1
- Fixed server-side rendering manifest resolution issue
- Improved `bundle_js_file_path` configuration flexibility for react-server-client-manifest.json

5. Troubleshooting Section

## Common Upgrade Issues

### Generator Prerequisites Error
If you see "ERROR: You have uncommitted changes", commit or stash your changes before running the generator.

### Shakapacker Version Mismatch
Error: "Shakapacker gem and node package versions do not match"
Solution: Ensure both gem and npm package are the same version (8.2.0 for v16.1.1)

### Test Failures After Upgrade
- Rebuild ReScript files if using ReScript: `yarn res:build`
- Clear webpack cache: `rm -rf public/packs*`
- Precompile assets: `rails assets:precompile`

Related Information

• PR demonstrating the upgrade: Update react_on_rails to v16.1.1 react-webpack-rails-tutorial#654
• Bug fix details: Fixed in PR Fix bug at resolving react-server-client-manifest.json file #1818

Benefits to Users

• Clear upgrade path from 16.0.x to 16.1.1
• Understanding of new development features
• Troubleshooting guidance for common issues
• Version compatibility clarity

This documentation would help users take full advantage of the improvements in v16.1.1 while avoiding common pitfalls during the upgrade process.

🤖 Generated with Claude Code