Prepare v9.1.0 release (#665)

* Update CHANGELOG and migration guide for v9.1.0 release
- Change Unreleased section to v9.1.0 with October 8, 2025 date
- Add prominent warning about SWC loose mode breaking change
- Add dedicated section in v9 upgrade guide explaining the breaking change
- Link from CHANGELOG to migration guide for detailed instructions
- Clarify that most projects need no changes
- Explain impact on Stimulus users and spread operators

This ensures users upgrading from v9.0.0 to v9.1.0 are aware of the
breaking change and know how to handle it if needed.

Author: justin808

CHANGELOG.md

@@ -11,21 +11,30 @@
 
 Changes since the last non-beta release.
 
+_No unreleased changes._
+
+## [v9.1.0] - October 8, 2025
+
+**⚠️ IMPORTANT:** This release includes a breaking change for SWC users. Please see the [v9 Upgrade Guide - SWC Loose Mode Breaking Change](./docs/v9_upgrade.md#swc-loose-mode-breaking-change-v910) for migration details.
+
 ### ⚠️ Breaking Changes
 
-- **SWC default configuration now uses `loose: false` for spec-compliant transforms** ([#657](https://github.com/shakacode/shakapacker/issues/657))
+- **SWC default configuration now uses `loose: false` for spec-compliant transforms** ([#658](https://github.com/shakacode/shakapacker/pull/658))
   - Previously, Shakapacker set `loose: true` by default in SWC configuration, which caused:
     - Silent failures with Stimulus controllers
     - Incorrect behavior with spread operators on iterables (e.g., `[...new Set()]`)
     - Deviation from both SWC and Babel upstream defaults
   - Now defaults to `loose: false`, matching SWC's default and fixing compatibility with Stimulus
   - This aligns with the previous fix to Babel configuration in [PR #107](https://github.com/shakacode/shakapacker/pull/107)
-  - **Migration:** If you need the old behavior for performance reasons, add to `config/swc.config.js`:
+  - **Migration:** Most projects need no changes as the new default provides spec-compliant behavior. Projects with Stimulus will benefit from this fix. See [v9 Upgrade Guide - SWC Loose Mode](./docs/v9_upgrade.md#swc-loose-mode-breaking-change-v910) for details
+  - If you must restore the old behavior (not recommended), add to `config/swc.config.js`:
     ```javascript
     module.exports = {
       options: {
         jsc: {
-          loose: true // Restore old behavior (not recommended)
+          // Only use this if you have code that requires loose transforms.
+          // This provides slightly faster build performance but may cause runtime bugs.
+          loose: true // Restore v9.0.0 behavior
         }
       }
     }
@@ -47,16 +56,16 @@ Changes since the last non-beta release.
   - Secure command execution (prevents shell injection)
   - Usage: `rails shakapacker:switch_bundler [webpack|rspack] [--install-deps] [--no-uninstall]`
   - See rake task help: `rails shakapacker:switch_bundler --help`
-- **Stimulus compatibility built into SWC migration** ([#657](https://github.com/shakacode/shakapacker/issues/657))
+- **Stimulus compatibility built into SWC migration** ([#658](https://github.com/shakacode/shakapacker/pull/658))
   - `rake shakapacker:migrate_to_swc` now creates `config/swc.config.js` with `keepClassNames: true`
   - Prevents SWC from mangling class names, which breaks Stimulus controller discovery
   - Includes React Fast Refresh configuration by default
-- **Comprehensive Stimulus documentation** for SWC users ([#657](https://github.com/shakacode/shakapacker/issues/657))
-  - Added "Using SWC with Stimulus" section to `docs/using_swc_loader.md`
+- **Comprehensive Stimulus documentation** for SWC users ([#658](https://github.com/shakacode/shakapacker/pull/658))
+  - Added "Using SWC with Stimulus" section to [docs/using_swc_loader.md](./docs/using_swc_loader.md#using-swc-with-stimulus)
   - Documents symptoms of missing configuration (silent failures)
   - Explains common errors like `env` and `jsc.target` conflicts
   - Added Stimulus compatibility checklist to migration guide
-- **Enhanced `rake shakapacker:doctor` for SWC configuration validation** ([#657](https://github.com/shakacode/shakapacker/issues/657))
+- **Enhanced `rake shakapacker:doctor` for SWC configuration validation** ([#658](https://github.com/shakacode/shakapacker/pull/658))
   - Detects `loose: true` in config and warns about potential issues
   - Detects missing `keepClassNames: true` when Stimulus is installed
   - Detects conflicting `jsc.target` and `env` configuration

docs/v9_upgrade.md

@@ -2,6 +2,8 @@
 
 This guide outlines new features, breaking changes, and migration steps for upgrading from Shakapacker v8 to v9.
 
+> **⚠️ Important for v9.1.0 Users:** If you're upgrading to v9.1.0 or later, please note the [SWC Configuration Breaking Change](#swc-loose-mode-breaking-change-v910) below. This affects users who previously configured SWC in v9.0.0.
+
 ## New Features
 
 ### TypeScript Support
@@ -41,6 +43,49 @@ See the [TypeScript Documentation](./typescript.md) for usage examples.
 - Remove custom scripts that set NODE_ENV before running the dev server
 - Remove `NODE_ENV=development` from your `bin/dev` or Procfile.dev
 
+## SWC Loose Mode Breaking Change (v9.1.0)
+
+> **⚠️ This breaking change was introduced in v9.1.0.** If you're upgrading from v9.0.0, pay special attention to this section.
+
+**What changed:** SWC default configuration now uses `loose: false` instead of `loose: true`.
+
+**Why:** The previous default of `loose: true` caused:
+
+- **Silent failures with Stimulus controllers** - Controllers wouldn't register properly
+- **Incorrect behavior with spread operators** on iterables (e.g., `[...new Set()]`)
+- **Deviation from SWC and Babel defaults** - Both tools default to `loose: false`
+
+**Impact:**
+
+- **Most projects:** No action needed. The new default is more correct and fixes bugs.
+- **Stimulus users:** This fixes silent controller failures you may have experienced.
+- **Projects relying on loose mode behavior:** May need to explicitly configure `loose: true` (not recommended).
+
+**When you might need the old behavior:**
+
+- If you have code that breaks with spec-compliant transforms
+- Note: `loose: true` provides slightly faster build times but generates less spec-compliant code
+
+**How to restore old behavior (not recommended):**
+
+Create or update `config/swc.config.js`:
+
+```javascript
+module.exports = {
+  options: {
+    jsc: {
+      // Only use this if you have code that requires loose transforms.
+      // This provides slightly faster build performance but may cause runtime bugs.
+      loose: true // Restore v9.0.0 behavior
+    }
+  }
+}
+```
+
+**Better solution:** Fix your code to work with spec-compliant transforms. The `loose: false` default aligns with both SWC and Babel standards and prevents subtle bugs.
+
+**Using Stimulus?** The new default includes `keepClassNames: true` to prevent SWC from mangling class names. If you use `rake shakapacker:migrate_to_swc`, this is configured automatically. See [Using SWC with Stimulus](./using_swc_loader.md#using-swc-with-stimulus) for details.
+
 ## Breaking Changes
 
 ### 1. CSS Modules Configuration Changed to Named Exports