Simplify v16.1.x upgrade documentation

justin808 · justin808 · commit 6409951dabc1 · 2025-12-04T18:33:51.000-10:00
- Use exact versions in examples (not ~&gt;)
- Remove package manager-specific commands (support all)
- Reduce verbosity for minor/patch release upgrade
- Focus on essential information
diff --git a/docs/upgrading/release-notes/16.1.0.md b/docs/upgrading/release-notes/16.1.0.md
@@ -2,20 +2,16 @@
 
 ## Upgrading from 16.0.x to 16.1.x
 
-This guide covers upgrading from React on Rails v16.0.x to v16.1.1.
-
-### Step 1: Update Dependencies
-
-**Gemfile:**
+Update your gem and npm package versions:
 
 ```ruby
-gem "react_on_rails", "~> 16.1.1"
-gem "shakapacker", "~> 8.2.0"  # Recommended for compatibility
+# Gemfile
+gem "react_on_rails", "16.1.1"
+gem "shakapacker", "8.2.0"
 ```
 
-**package.json:**
-
 ```json
+// package.json
 {
   "dependencies": {
     "react-on-rails": "16.1.1",
@@ -24,67 +20,21 @@ gem "shakapacker", "~> 8.2.0"  # Recommended for compatibility
 }
 ```
 
-**Important:** The shakapacker gem and npm package versions MUST match exactly.
-
-### Step 2: Install Updates
-
-```bash
-bundle update react_on_rails shakapacker
-yarn install  # or npm install
-```
-
-### Step 3: Run the Generator (Optional)
+Then run `bundle install` and your package manager's install command.
 
-Run the generator to get the latest improvements:
+**Important:** The shakapacker gem and npm package versions must match exactly.
 
-```bash
-rails generate react_on_rails:install
-```
-
-**Note:** The generator will prompt to overwrite files. Review each change carefully, especially if you have customizations. Key files that may be updated:
-
-- `bin/dev` - Enhanced development workflow
-- Webpack configurations
-- `shakapacker.yml` settings
-- TypeScript configuration
+## New Features in v16.1.0
 
-### Step 4: Use the New Doctor Command
+### Doctor Rake Task
 
-v16.1.0 introduces a diagnostic rake task to validate your setup:
+New diagnostic command for troubleshooting setup issues:
 
 ```bash
 rake react_on_rails:doctor
+VERBOSE=true rake react_on_rails:doctor  # For detailed output
 ```
 
-For detailed output:
-
-```bash
-VERBOSE=true rake react_on_rails:doctor
-```
-
-The doctor command checks:
-
-- Environment prerequisites
-- Dependencies and version compatibility
-- Rails integration
-- Webpack configuration
-- Shakapacker setup
-
-### Step 5: Test Your Application
-
-```bash
-# Test asset compilation
-bundle exec rails assets:precompile
-
-# Test development server
-bin/dev
-
-# Run your test suite
-bundle exec rspec  # or your test command
-```
-
-## New Features in v16.1.0
-
 ### Server Bundle Security
 
 New configuration options for enhanced server bundle security:
@@ -93,153 +43,38 @@ New configuration options for enhanced server bundle security:
 # config/initializers/react_on_rails.rb
 ReactOnRails.configure do |config|
   # Directory for server bundle output (default: "ssr-generated")
-  # Set to nil to load from public directory (legacy behavior)
   config.server_bundle_output_path = "ssr-generated"
 
   # When enabled, server bundles only load from private directories
-  # (default: false for backward compatibility)
   config.enforce_private_server_bundles = true
 end
 ```
 
-**Bundle Path Resolution Logic:**
-
-1. If `server_bundle_output_path` is set, server bundles load from that directory
-2. If not set, falls back to client bundle directory (public output path)
-3. When `enforce_private_server_bundles` is enabled:
-   - Server bundles only load from the private directory
-   - No fallback to public directory (improved security)
-
-### Doctor Rake Task
-
-New diagnostic command for troubleshooting:
-
-```bash
-rake react_on_rails:doctor
-```
-
-Provides comprehensive checks for:
-
-- Environment prerequisites
-- Dependency versions
-- Rails integration
-- Webpack configuration
-- Common setup issues
-
 ### Generator Improvements
 
-- **Modern TypeScript patterns**: Better type inference instead of explicit annotations
-- **Optimized tsconfig.json**: Uses `"moduleResolution": "bundler"` for bundler compatibility
-- **Enhanced Redux TypeScript**: Improved type safety with modern React patterns (useMemo, type-only imports)
-- **Smart bin/dev defaults**: Auto-navigates to `/hello_world` route for immediate component visibility
-- **Cleaner generated code**: Follows modern React and TypeScript best practices
-
-## Deprecations
-
-### `generated_assets_dirs` Configuration
-
-The `config.generated_assets_dirs` option is deprecated. Remove it from `config/initializers/react_on_rails.rb`.
-
-**Why:** Since Shakapacker is now required, asset paths are automatically determined from `shakapacker.yml`.
-
-**Migration:** Use `public_output_path` in `config/shakapacker.yml` to customize asset output location.
-
-### `generated_assets_full_path` Method
-
-Use `public_bundles_full_path` instead for clarity about webpack bundles in public directories.
-
-## Bug Fixes in v16.1.1
+- Modern TypeScript patterns with better type inference
+- Optimized tsconfig.json with `"moduleResolution": "bundler"`
+- Enhanced Redux TypeScript integration
+- Smart `bin/dev` defaults
 
-- **React Server Components**: Fixed bug in resolving `react-server-client-manifest.json` file path. The manifest file path is now correctly resolved using `bundle_js_file_path` for improved configuration flexibility. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)
+## Bug Fixes
 
-## Bug Fixes in v16.1.0
+### v16.1.1
 
-- **Doctor rake task**: Fixed LoadError when using packaged gem
-- **Packs generator**: Fixed error when `server_bundle_js_file` is empty
-- **Non-Packer compatibility**: Fixed NoMethodError in environments without Shakapacker
-- **Shakapacker version requirements**: Fixed inconsistent version requirements between basic pack generation (6.5.1+) and advanced auto-bundling (7.0.0+)
+- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818))
 
-## Security Enhancements
+### v16.1.0
 
-- **Private Server Bundle Enforcement**: Server bundles bypass public directory fallbacks when `enforce_private_server_bundles` is enabled
-- **Path Validation**: Validates `server_bundle_output_path` points to private directories when enforcement is enabled
-- **Command injection fixes**: Replaced unsafe string interpolation with secure array-based system calls
-- **Input validation**: Enhanced package manager validation and argument sanitization
-- **Hardened DOM selectors**: Using `CSS.escape()` and proper JavaScript escaping for XSS protection
-
-## Version Compatibility
-
-| react_on_rails | shakapacker (gem) | shakapacker (npm) | Rails | Ruby |
-| -------------- | ----------------- | ----------------- | ----- | ---- |
-| 16.1.x         | 8.2.0+            | 8.2.0+            | 6.0+  | 3.2+ |
-| 16.0.x         | 6.0.0+            | 6.0.0+            | 6.0+  | 3.2+ |
-
-**Recommended versions:**
-
-- Shakapacker 8.2.0 (gem and npm versions must match)
-- React 18+
-- Node.js 20+
-- Ruby 3.2+
-
-## Common Upgrade Issues
-
-### Generator Prerequisites Error
-
-```
-ERROR: You have uncommitted changes
-```
+- Fixed LoadError in `rake react_on_rails:doctor` when using packaged gem
+- Fixed packs generator error when `server_bundle_js_file` is empty
+- Fixed NoMethodError in environments without Shakapacker
+- Fixed inconsistent Shakapacker version requirements
 
-**Solution:** Commit or stash your changes before running the generator.
-
-### Shakapacker Version Mismatch
-
-```
-Shakapacker gem and node package versions do not match
-```
-
-**Solution:** Ensure both gem and npm package are the same version:
-
-```bash
-# Check versions
-bundle show shakapacker
-yarn list shakapacker  # or npm ls shakapacker
-
-# Update to match
-bundle update shakapacker
-yarn upgrade shakapacker@8.2.0
-```
-
-### Test Failures After Upgrade
-
-1. **Rebuild ReScript files** (if using ReScript):
-
-   ```bash
-   yarn res:build
-   ```
-
-2. **Clear webpack cache**:
-
-   ```bash
-   rm -rf node_modules/.cache
-   rm -rf public/packs*
-   ```
-
-3. **Precompile assets**:
-   ```bash
-   rails assets:precompile
-   ```
-
-### Server Bundle Not Found
-
-If you're using server-side rendering and the server bundle isn't found:
+## Deprecations
 
-1. Check `config.server_bundle_output_path` is correctly set
-2. Run `rake react_on_rails:doctor` to diagnose issues
-3. Verify webpack builds both client and server bundles
+Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`.
 
 ## Related Resources
 
 - [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md)
 - [Configuration Reference](../../api-reference/configuration.md)
-- [Troubleshooting Guide](../../deployment/troubleshooting.md)
-- [Example upgrade PR: react-webpack-rails-tutorial#654](https://github.com/shakacode/react-webpack-rails-tutorial/pull/654)
diff --git a/docs/upgrading/upgrading-react-on-rails.md b/docs/upgrading/upgrading-react-on-rails.md
@@ -23,53 +23,9 @@ rails generate react_on_rails:install
 
 ## Upgrading to v16.1.x (from v16.0.x)
 
-For detailed upgrade instructions, see the [v16.1.x Release Notes](release-notes/16.1.0.md).
+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.
 
-### Quick Summary
-
-v16.1.x is a minor release with new features and bug fixes:
-
-- **New `rake react_on_rails:doctor` command** for diagnosing setup issues
-- **Server bundle security enhancements** with `server_bundle_output_path` and `enforce_private_server_bundles` options
-- **Generator improvements** with modern TypeScript patterns and better defaults
-- **Bug fix (v16.1.1)**: Fixed RSC manifest file path resolution
-
-### Upgrade Steps
-
-1. Update dependencies:
-
-   ```ruby
-   # Gemfile
-   gem "react_on_rails", "~> 16.1.1"
-   gem "shakapacker", "~> 8.2.0"
-   ```
-
-   ```json
-   // package.json - versions must match exactly
-   {
-     "dependencies": {
-       "react-on-rails": "16.1.1",
-       "shakapacker": "8.2.0"
-     }
-   }
-   ```
-
-2. Install and verify:
-
-   ```bash
-   bundle update react_on_rails shakapacker
-   yarn install
-   rake react_on_rails:doctor  # New diagnostic command
-   ```
-
-3. Optionally run generator for latest improvements:
-   ```bash
-   rails generate react_on_rails:install
-   ```
-
-### Deprecation Notice
-
-Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`.
+**Deprecation:** Remove `config.generated_assets_dirs` from your configuration if present.
 
 ## Upgrading to v16 (from v14/v15)
 
