shakapacker 9.6.0.rc.0 → 9.6.0.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5240d4875989d1257b2c24656db7b29c5d052a9c99e22b9203565bf615aaf43
-  data.tar.gz: 855e3c61ff9169c2f4a34cc864d80f41299e48fd2530fb0def09e5bd9e07651f
+  metadata.gz: f8de376ed8bf26aa80f043c1b4f1edfe9fe14e76b8b5db9d4d4bdfc6fc1b0c62
+  data.tar.gz: 84db935f44746cc5ec67a1e71018bab24d1a17c2be17a27a4d6d894e35e4e106
 SHA512:
-  metadata.gz: 719593b91e0dd86f68db334fe533a76e05ebf7862e04162039b066182bc52642e4c200d0394e6f3cbfaea8a8600d5340d20d9a5cd54bd389c40e4d4ff8c1f055
-  data.tar.gz: 80f22641a2e9cba2ab9a8ccda6095133e636165185914b8ae1b6f7a85f1b860834913dc4a697db7d1785f001420e47aefad34584389c0221dc7eb7e0f9778957
+  metadata.gz: c9b75f026df4c043286fe9d068651de5c67eecd2c34a6946a6d708498d6c9cd032db716805126eb280ef72ef828582391d0579f304d30ccf736fd6d0d3ea6456
+  data.tar.gz: 5574ca0d5f1992980e8f2cb615c76fb0934201493d0994fcef5a6824040ba3eb6a01d4aae087fc2941b3fa52529eb6f6ec71e1b4230f9c44c6379d4b0fdb141e

data/.claude/commands/update-changelog.md

@@ -2,6 +2,68 @@
 
 You are helping to add an entry to the CHANGELOG.md file for the Shakapacker project.
 
+## Arguments
+
+This command accepts an optional argument: `$ARGUMENTS`
+
+- **No argument** (`/update-changelog`): Add entries to `[Unreleased]` without stamping a version header. Use this during development.
+- **`release`** (`/update-changelog release`): Add entries and stamp a version header. Auto-compute the next version based on changes (breaking → major, added features → minor, fixes → patch). Then `rake create_release` (with no args) will pick up this version automatically.
+- **`rc`** (`/update-changelog rc`): Same as `release`, but stamps an RC prerelease version (e.g., `v9.7.0-rc.0`). Auto-increments the RC index if prior RCs exist for the same base version.
+- **`beta`** (`/update-changelog beta`): Same as `rc`, but stamps a beta prerelease version (e.g., `v9.7.0-beta.0`).
+
+## When to Use This
+
+This command serves three use cases at different points in the release lifecycle:
+
+**During development** — Add entries to `[Unreleased]` as PRs merge:
+
+- Run `/update-changelog` to find merged PRs missing from the changelog
+- Entries accumulate under `## [Unreleased]`
+
+**Before a release** — Stamp a version header and prepare for release:
+
+- Run `/update-changelog release` (or `rc` or `beta`) to add entries AND stamp the version header
+- The version is auto-computed from changelog content (see "Auto-Computing the Next Version" below)
+- Commit and push CHANGELOG.md
+- Then run `rake create_release` (no args needed — it reads the version from CHANGELOG.md)
+- The release task automatically creates a GitHub release from the changelog section
+
+**After a release you forgot to update the changelog for** — Catch-up mode:
+
+- The command can retroactively find commits between tags and add missing entries
+- Ask the user whether to stamp a version header or add to `[Unreleased]`
+
+### Why changelog comes BEFORE the release
+
+- `create_release` automatically creates a GitHub release if a changelog section exists — no separate `sync_github_release` step needed
+- The release task warns if no changelog section is found for the target version
+- A premature version header (if release fails) is harmless — you'll release eventually
+- A missing changelog after release means GitHub release must be created manually
+
+## Auto-Computing the Next Version
+
+When stamping a version header (`release`, `rc`, or `beta`), compute the next version as follows:
+
+1. **Find the latest stable version tag** using semver sort:
+
+   ```bash
+   git tag -l 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
+   ```
+
+2. **Determine bump type from changelog content**:
+   - If changes include `### Breaking Changes` or `### ⚠️ Breaking Changes` → **major** bump
+   - If changes include `### Added` or `### New Features` → **minor** bump
+   - If changes only include `### Fixed`, `### Security`, `### Improved`, `### Changed`, `### Deprecated` → **patch** bump
+
+3. **Compute the version**:
+   - For `release`: Apply the bump to the latest stable tag (e.g., `9.5.0` + minor → `9.6.0`)
+   - For `rc`: Apply the bump, then find the next RC index (e.g., if `v9.6.0-rc.0` tag exists → `v9.6.0-rc.1`)
+   - For `beta`: Same as RC but with beta suffix
+
+4. **Verify**: Check that the computed version is newer than ALL existing tags (stable and prerelease). If not, ask the user what to do.
+
+5. **Show the computed version to the user** and ask for confirmation before stamping the header.
+
 ## Critical Requirements
 
 1. **User-visible changes only**: Only add changelog entries for user-visible changes:
@@ -74,6 +136,21 @@ Entries should be organized under these section headings. The project uses both
 
 **Only include section headings that have entries.**
 
+### Version Header Format
+
+**Stable releases**: `## [v9.6.0] - March 7, 2026`
+
+**Prerelease versions** (RC and beta): Use npm semver format with dashes, NOT RubyGems dot format:
+
+- Correct: `## [v9.6.0-rc.1]` (npm semver — this is what `sync_github_release` expects)
+- Wrong: `## [v9.6.0.rc.1]` (RubyGems format — do NOT use this in CHANGELOG.md headers)
+
+This matters because the release rake tasks convert between formats:
+
+- Git tags use npm format: `v9.6.0-rc.1`
+- Gem versions use RubyGems format: `9.6.0.rc.1`
+- CHANGELOG.md headers must match git tag format: `## [v9.6.0-rc.1]`
+
 ### Version Management
 
 After adding entries, use the rake task to manage version headers:
@@ -110,16 +187,17 @@ When a new version is released:
 ### For Regular Changelog Updates
 
 1. **ALWAYS fetch latest changes first**:
-   - **CRITICAL**: Run `git fetch origin main` to ensure you have the latest commits
+   - **CRITICAL**: Run `git fetch origin main --tags` to ensure you have the latest commits AND tags
    - The workspace may be behind origin/main, causing you to miss recently merged PRs
    - After fetching, use `origin/main` for all comparisons, NOT local `main` branch
 
 2. **Determine the correct version tag to compare against**:
-   - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
-   - Find the latest version tag and its date
-   - Compare origin/main branch date to the tag date
-   - If the tag is NEWER than origin/main, it means the branch needs to be updated to include the tag's commits
-   - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead
+   - List all version tags sorted by semver: `git tag -l 'v*' --sort=-v:refname | head -10`
+   - This correctly sorts RC/beta tags (e.g., `v9.6.0-rc.1` sorts after `v9.6.0-rc.0` and before `v9.6.0`)
+   - The latest tag may be a stable release, RC, or beta — handle all cases
+   - Compare origin/main branch date to the tag date using: `git log -1 --format="%ai" origin/main` and `git log -1 --format="%ai" <tag>`
+   - If the tag is NEWER than origin/main, the branch needs updating to include the tag's commits
+   - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits in the branch but not the tag, AND `git log BRANCH..TAG` to check if the tag is ahead
 
 3. **Check commits and version boundaries**:
    - **IMPORTANT**: Use `origin/main` in all commands below, not local `main`
@@ -162,37 +240,44 @@ When a new version is released:
 
 10. **Show the user** the added or moved entries and explain what was done.
 
-### For Beta to Non-Beta Version Release
+### For Prerelease Versions (RC and Beta)
 
-When releasing from beta to a stable version (e.g., v9.1.0-beta.3 → v9.1.0):
+When the user passes `rc` or `beta` as an argument (or when creating a prerelease section manually):
 
-1. **Remove all beta version labels** from the changelog:
-   - Change `## [v9.1.0-beta.1]`, `## [v9.1.0-beta.2]`, etc. to a single `## [v9.1.0]` section
-   - Combine all beta entries into the stable release section
+1. **Find the latest tag** (stable or prerelease) using semver sort:
 
-2. **Consolidate duplicate entries**:
-   - If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
-   - Remove redundant changelog entries for fixes to beta features
-   - Keep the most recent/accurate description of each change
+   ```bash
+   git tag -l 'v*' --sort=-v:refname | head -10
+   ```
 
-3. **Update version diff links** at the bottom to point to the stable version
+2. **Auto-compute the next prerelease version** using the process in "Auto-Computing the Next Version" above.
 
-### For New Beta Version Release
+3. **Use npm semver format** for the version header:
+   - RC: `## [v9.6.0-rc.1]`
+   - Beta: `## [v9.6.0-beta.2]`
 
-When creating a new beta version, ask the user which approach to take:
+4. **Always collapse prior prereleases into the current prerelease** (this is the default behavior):
+   - Combine all prior prerelease changelog entries into the new prerelease version section
+   - Remove previous prerelease version sections (e.g., remove `## [v9.6.0-rc.0]` when creating `## [v9.6.0-rc.1]`)
+   - Add any new user-visible changes from commits since the last prerelease
+   - Update version diff links to point from the last stable version to the new prerelease
+   - This keeps the changelog clean with a single prerelease section that accumulates all changes since the last stable release
 
-**Option 1: Process changes since last beta**
+### For Prerelease to Stable Version Release
 
-- Only add entries for commits since the previous beta version
-- Maintains detailed history of what changed in each beta
+When releasing from prerelease to a stable version (e.g., v9.6.0-rc.1 → v9.6.0):
 
-**Option 2: Collapse all prior betas into current beta**
+1. **Remove all prerelease version labels** from the changelog:
+   - Change `## [v9.6.0-rc.0]`, `## [v9.6.0-rc.1]`, etc. to a single `## [v9.6.0]` section
+   - Also handle beta versions: `## [v9.6.0-beta.1]` etc.
+   - Combine all prerelease entries into the stable release section
 
-- Combine all beta changelog entries into the new beta version
-- Removes previous beta version sections
-- Cleaner changelog with less version noise
+2. **Consolidate duplicate entries**:
+   - If bug fixes or changes were made to features introduced in earlier prereleases, keep only the final state
+   - Remove redundant changelog entries for fixes to prerelease features
+   - Keep the most recent/accurate description of each change
 
-After the user chooses, proceed with that approach.
+3. **Update version diff links** at the bottom to point to the stable version
 
 ## Examples
 

data/.github/workflows/claude-code-review.yml

@@ -12,6 +12,7 @@ jobs:
       contents: read
       pull-requests: write
       issues: write
+      id-token: write
 
     steps:
       - name: Checkout repository

data/CHANGELOG.md

@@ -11,6 +11,8 @@
 
 Changes since the last non-beta release.
 
+## [v9.6.0-rc.2] - March 7, 2026
+
 ### Security
 
 - Removed default `Access-Control-Allow-Origin: *` header from dev server configuration. This header allowed any website to access dev server resources. **If your setup runs webpack-dev-server on a different port from your Rails server, uncomment the `headers` section in `config/shakapacker.yml` to restore cross-origin asset loading.** [PR #936](https://github.com/shakacode/shakapacker/pull/936) by [justin808](https://github.com/justin808). Fixes [#935](https://github.com/shakacode/shakapacker/issues/935).
@@ -35,6 +37,7 @@ Changes since the last non-beta release.
 
 ### Changed
 
+- **Changed default file rule type from `asset/resource` to `asset`**. [PR #901](https://github.com/shakacode/shakapacker/pull/901) by [justin808](https://github.com/justin808). Static assets (images, fonts, SVGs) now use webpack/rspack's `asset` type instead of `asset/resource`, allowing the bundler to automatically inline small files as data URIs for better performance.
 - Allow `compression-webpack-plugin` v12. [PR #937](https://github.com/shakacode/shakapacker/pull/937) by [G-Rath](https://github.com/G-Rath).
 - **BREAKING: sass-loader now defaults to modern Sass API**. [PR #879](https://github.com/shakacode/shakapacker/pull/879) by [justin808](https://github.com/justin808). The sass-loader configuration now uses `api: "modern"` instead of the deprecated legacy API. This improves compatibility with plugins like sass-resources-loader that require the modern API. If you experience issues after upgrading, you can revert to the legacy API by customizing your webpack config:
 
@@ -63,12 +66,13 @@ Changes since the last non-beta release.
 - **Fixed orphaned webpack/rspack processes when foreman receives SIGTERM**. [PR #888](https://github.com/shakacode/shakapacker/pull/888) by [jordan-brough](https://github.com/jordan-brough). When running under foreman, sending SIGTERM to foreman (e.g. `kill <pid>`) would kill the Ruby shakapacker process but leave the webpack/rspack child process running as an orphan. DevServerRunner now uses `exec` to replace the Ruby process entirely, and Runner uses `spawn` with SIGTERM forwarding to ensure the child process is properly terminated.
 - **Fixed missing-environment fallback to use production instead of development**. [PR #894](https://github.com/shakacode/shakapacker/pull/894) by [justin808](https://github.com/justin808). When a Rails environment (e.g., staging) is not defined in `shakapacker.yml`, Shakapacker now falls back to the `production` configuration instead of `development`. This ensures unknown environments get production-optimized webpack/rspack builds by default.
 - **Fixed installer writing wrong shakapacker version in package.json**. [PR #899](https://github.com/shakacode/shakapacker/pull/899) by [justin808](https://github.com/justin808). The `shakapacker:install` generator now keeps the `package.json` dependency value in sync with the exact version or path that was requested, instead of relying on the post-install value which could differ.
+- **Fixed `privateOutputPath` not being computed in JavaScript config**. [PR #891](https://github.com/shakacode/shakapacker/pull/891) by [ihabadham](https://github.com/ihabadham). The `private_output_path` setting from `shakapacker.yml` is now properly resolved to an absolute path and exposed as `privateOutputPath` in the JavaScript configuration, matching the behavior already present in the Ruby configuration.
 - **Fixed installer not updating `shakapacker.yml` when selecting a non-default transpiler**. [PR #895](https://github.com/shakacode/shakapacker/pull/895) by [codex-rs](https://github.com/apps/codex-rs). Installing with `JAVASCRIPT_TRANSPILER=babel` (or `esbuild`) now correctly updates `config/shakapacker.yml` to match the selected transpiler instead of leaving it set to `swc`. Previously, a quote mismatch in the `gsub_file` call meant the config was never actually updated, and the condition also excluded `JAVASCRIPT_TRANSPILER=babel` from the update entirely. Additionally, `JAVASCRIPT_TRANSPILER=babel` no longer installs SWC packages.
 - **Fixed ENOENT crash on clean builds when using `webpack-assets-manifest` v6 with `merge: true`**. [PR #931](https://github.com/shakacode/shakapacker/pull/931) by [justin808](https://github.com/justin808). Seeds an empty `{}` manifest file before instantiating the plugin, so the merge read succeeds on first build rather than throwing an unhandled ENOENT.
 - **Improved error message when manifest is empty or missing**. [PR #872](https://github.com/shakacode/shakapacker/pull/872) by [justin808](https://github.com/justin808). When the bundler is still compiling (empty manifest) or hasn't run yet (missing manifest file), users now see clear, actionable error messages instead of the generic 7-point checklist.
 - **Fixed NODE_ENV=test causing DefinePlugin warnings**. [PR #870](https://github.com/shakacode/shakapacker/pull/870) by [justin808](https://github.com/justin808). When RAILS_ENV=test, Shakapacker now sets NODE_ENV=development instead of NODE_ENV=test. This prevents webpack/rspack DefinePlugin conflicts since these bundlers only recognize "development" and "production" as valid NODE_ENV values.
 - **Fixed `--json` flag output being corrupted by log messages**. [PR #869](https://github.com/shakacode/shakapacker/pull/869) by [justin808](https://github.com/justin808). When `--json` is in the command arguments, `[Shakapacker]` log messages are now written to stderr instead of stdout, keeping stdout clean for valid JSON output. This allows `bin/shakapacker --profile --json` to be piped to tools like `webpack-bundle-analyzer`. Normal (non-JSON) usage is unchanged. Resolves [#868](https://github.com/shakacode/shakapacker/issues/868).
-- **Require explicit truthy values for `SKIP` and `FORCE` installer env vars**. [PR #926](https://github.com/shakacode/shakapacker/pull/926) by [justin808](https://github.com/justin808). Previously, any set value (including `"false"` or `"0"`) would activate skip/force mode. Now only explicit truthy values (`true`, `1`, `yes`, case-insensitive) are recognized. This behavior change may require CI/scripts that relied on `FORCE=<any non-empty value>` to switch to `FORCE=true`.
+- **Require explicit truthy values for all installer env vars**. [PR #926](https://github.com/shakacode/shakapacker/pull/926), [PR #943](https://github.com/shakacode/shakapacker/pull/943) by [justin808](https://github.com/justin808). Previously, any set value (including `"false"` or `"0"`) would activate these flags. Now only explicit truthy values (`true`, `1`, `yes`, case-insensitive) are recognized for `SKIP`, `FORCE`, `USE_BABEL_PACKAGES`, `SHAKAPACKER_USE_TYPESCRIPT`, and `SKIP_COMMON_LOADERS`. This behavior change may require CI/scripts that relied on arbitrary non-empty values to switch to recognized truthy values like `true`.
 
 ### Documentation
 
@@ -116,7 +120,7 @@ Changes since the last non-beta release.
 
 - **Added `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` environment variable to skip precompile hook**. [PR #850](https://github.com/shakacode/shakapacker/pull/850) by [justin808](https://github.com/justin808). Set `SHAKAPACKER_SKIP_PRECOMPILE_HOOK=true` to skip the precompile hook during compilation. This is useful when using process managers like Foreman or Overmind to run the hook once before starting multiple webpack processes, preventing duplicate hook execution. **Migration tip:** If you have a custom `bin/dev` script that starts multiple webpack processes, you can now run the precompile hook once in the script and set this environment variable to prevent each webpack process from running the hook again. See the [precompile hook documentation](./docs/precompile_hook.md#skipping-the-hook) for implementation examples.
 
-## [v9.3.4-beta.0] - November 17, 2025
+## [v9.3.4] - November 17, 2025
 
 ### Fixed
 
@@ -864,10 +868,11 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.5.0...main
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.6.0-rc.2...main
+[v9.6.0-rc.2]: https://github.com/shakacode/shakapacker/compare/v9.5.0...v9.6.0-rc.2
 [v9.5.0]: https://github.com/shakacode/shakapacker/compare/v9.4.0...v9.5.0
 [v9.4.0]: https://github.com/shakacode/shakapacker/compare/v9.3.4...v9.4.0
-[v9.3.4-beta.0]: https://github.com/shakacode/shakapacker/compare/v9.3.3...v9.3.4-beta.0
+[v9.3.4]: https://github.com/shakacode/shakapacker/compare/v9.3.3...v9.3.4
 [v9.3.3]: https://github.com/shakacode/shakapacker/compare/v9.3.2...v9.3.3
 [v9.3.2]: https://github.com/shakacode/shakapacker/compare/v9.3.1...v9.3.2
 [v9.3.1]: https://github.com/shakacode/shakapacker/compare/v9.3.0...v9.3.1

data/docs/releasing.md

@@ -9,6 +9,7 @@ This guide is for Shakapacker maintainers who need to publish a new release.
    ```bash
    bundle install              # Installs gem-release
    yarn global add release-it  # Installs release-it for npm publishing
+   gh --version                # Required for automatic GitHub release creation
    ```
 
 2. **Ensure you have publishing access:**
@@ -19,53 +20,97 @@ This guide is for Shakapacker maintainers who need to publish a new release.
    - npm: 2FA is required for publishing
    - RubyGems: 2FA is required for publishing
 
+4. **Authenticate GitHub CLI:**
+   - Run `gh auth login` and ensure your account/token has write access to this repository
+   - Required for automatic GitHub release creation after publishing
+
 ## Release Process
 
-### 1. Prepare the Release
+### 1. Update the Changelog
 
-Before running the release task:
+**Always update CHANGELOG.md before running the release task.** The release task reads the version from CHANGELOG.md and automatically creates a GitHub release from the changelog section.
 
 1. Ensure all desired changes are merged to `main` branch
-2. Update `CHANGELOG.md` with the new version and release notes
-3. Commit the CHANGELOG changes
-4. Ensure your working directory is clean (`git status` shows no uncommitted changes)
+2. Run `/update-changelog release` (or `rc` or `beta` for prereleases) to:
+   - Find merged PRs missing from the changelog
+   - Add changelog entries under the appropriate category headings
+   - Auto-compute the next version based on changes (breaking → major, features → minor, fixes → patch)
+   - Stamp the version header (e.g., `## [v9.6.0] - March 7, 2026`)
+3. Review the changelog entries and verify the computed version
+4. Commit and push CHANGELOG.md
+
+If you forget this step, the release task will print a warning and the GitHub release will need to be created manually afterward using `sync_github_release`.
 
 ### 2. Run the Release Task
 
-The automated release task handles the entire release process:
+The simplest way to release is with no arguments — the task reads the version from CHANGELOG.md:
 
 ```bash
-# For a specific version (e.g., 9.1.0)
-bundle exec rake create_release[9.1.0]
+# Recommended: reads version from CHANGELOG.md (requires step 1)
+bundle exec rake create_release
+
+# For a specific version (overrides CHANGELOG.md detection)
+bundle exec rake "create_release[9.1.0]"
 
 # For a beta release (note: use period, not dash)
-bundle exec rake create_release[9.2.0.beta.1]  # Creates npm package 9.2.0-beta.1
+bundle exec rake "create_release[9.2.0.beta.1]"  # Creates npm package 9.2.0-beta.1
 
-# For a patch version bump (auto-increments)
-bundle exec rake create_release
+# For a release candidate
+bundle exec rake "create_release[9.6.0.rc.0]"
 
 # Dry run to test without publishing
-bundle exec rake create_release[9.1.0,true]
+bundle exec rake "create_release[9.1.0,true]"
+
+# Override version policy checks (monotonic + changelog/bump consistency)
+RELEASE_VERSION_POLICY_OVERRIDE=true bundle exec rake "create_release[9.1.0]"
+bundle exec rake "create_release[9.1.0,false,true]"
 ```
 
+When called with no arguments, `create_release`:
+
+1. Reads the first versioned header from CHANGELOG.md (e.g., `## [v9.6.0]`)
+2. Compares it to the current gem version
+3. If the changelog version is newer, prompts for confirmation and uses it
+4. If no new version is found, falls back to a patch bump
+
+Dry runs use a temporary git worktree so version bumps and installs do not modify your current checkout.
+
+`create_release` validates release-version policy before publishing:
+
+- Target version must be greater than the latest tagged release.
+- If the versioned target changelog section exists (`## [vX.Y.Z...]`; not `UNRELEASED`), it maps to expected bump type:
+  - Breaking changes => major bump
+  - Added/New Features/Features/Enhancements => minor bump
+  - Fixed/Fixes/Bug Fixes/Security/Improved/Deprecated => patch bump
+  - Other headings => no inferred bump level (consistency check is skipped)
+
+Use override only when needed:
+
+- `RELEASE_VERSION_POLICY_OVERRIDE=true`
+- Or task arg override (`create_release[..., ..., true]`)
+
 ### 3. What the Release Task Does
 
 The `create_release` task automatically:
 
-1. **Pulls latest changes** from the repository
-2. **Bumps version numbers** in:
+1. **Validates release prerequisites**:
+   - Verifies npm authentication
+   - Warns if CHANGELOG.md section is missing for the target version
+2. **Pulls latest changes** from the repository
+3. **Bumps version numbers** in:
    - `lib/shakapacker/version.rb` (Ruby gem version)
    - `package.json` (npm package version - converted from Ruby format)
-3. **Publishes to npm:**
+4. **Publishes to npm:**
    - Prompts for npm OTP (2FA code)
    - Creates git tag
    - Pushes to GitHub
-4. **Publishes to RubyGems:**
+5. **Publishes to RubyGems:**
    - Prompts for RubyGems OTP (2FA code)
-5. **Updates spec/dummy lockfiles:**
+6. **Updates spec/dummy lockfiles:**
    - Runs `bundle install` to update `Gemfile.lock`
    - Runs `npm install` to update `package-lock.json` (yarn.lock may also be updated for multi-package-manager compatibility testing)
-6. **Commits and pushes lockfile changes** automatically
+7. **Commits and pushes lockfile changes** automatically
+8. **Creates GitHub release** from CHANGELOG.md (if the matching section exists)
 
 ### 4. Version Format
 
@@ -79,17 +124,25 @@ The task automatically converts Ruby gem format to npm semver format:
 - Ruby: `9.2.0.beta.1` → npm: `9.2.0-beta.1`
 - Ruby: `9.0.0.rc.2` → npm: `9.0.0-rc.2`
 
+**CHANGELOG.md headers** use npm semver format (with dashes):
+
+- `## [v9.6.0-rc.1]` — correct (matches git tag format)
+- `## [v9.6.0.rc.1]` — wrong (RubyGems format, will not be found by release tasks)
+
 **Examples:**
 
 ```bash
 # Regular release
-bundle exec rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+bundle exec rake "create_release[9.1.0]"  # Gem: 9.1.0, npm: 9.1.0
 
 # Beta release
-bundle exec rake create_release[9.2.0.beta.1]  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
+bundle exec rake "create_release[9.2.0.beta.1]"  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
 
 # Release candidate
-bundle exec rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+bundle exec rake "create_release[10.0.0.rc.1]"  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+
+# Prerelease: use /update-changelog rc first, then create_release reads it
+bundle exec rake create_release  # reads v10.0.0-rc.0 from CHANGELOG.md
 ```
 
 ### 5. During the Release
@@ -97,7 +150,9 @@ bundle exec rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc
 1. When prompted for **npm OTP**, enter your 2FA code from your authenticator app
 2. Accept defaults for release-it options
 3. When prompted for **RubyGems OTP**, enter your 2FA code
-4. The script will automatically commit and push lockfile updates
+4. If using `create_release` with no version, confirm the version detected from CHANGELOG.md (or the computed patch version)
+5. The script will automatically commit and push lockfile updates
+6. The script will automatically create a GitHub release (if CHANGELOG.md section exists)
 
 ### 6. After Release
 
@@ -118,6 +173,25 @@ bundle exec rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc
    - Tweet about major releases
    - Update documentation if needed
 
+### Syncing GitHub Releases Manually
+
+If the automatic GitHub release creation was skipped (e.g., CHANGELOG.md section was missing during release), you can create it manually after updating the changelog:
+
+1. Update `CHANGELOG.md` with the published version section
+   - For prerelease entries, use npm semver header format with dashes, for example `## [v9.6.0-rc.1]`
+2. Commit and push `CHANGELOG.md`
+3. Run:
+
+```bash
+# Stable
+bundle exec rake "sync_github_release[9.6.0]"
+
+# Prerelease
+bundle exec rake "sync_github_release[9.6.0.rc.1]"
+```
+
+`sync_github_release` reads release notes from the matching `CHANGELOG.md` section and creates/updates the GitHub release for the corresponding tag.
+
 ## Troubleshooting
 
 ### Uncommitted Changes After Release
@@ -141,6 +215,18 @@ If publishing fails partway through:
 3. If RubyGems failed: Fix the issue and manually run `gem release`
 4. Then manually update and commit spec/dummy lockfiles
 
+### GitHub Release Sync Fails
+
+If package publishing succeeds but GitHub release creation fails:
+
+1. Fix GitHub auth (`gh auth login`) or permissions
+2. Ensure `CHANGELOG.md` has matching header `## [vX.Y.Z...]` (npm format for prereleases)
+3. Rerun only:
+
+   ```bash
+   bundle exec rake "sync_github_release[<gem_version>]"
+   ```
+
 ### Wrong Version Format
 
 If you accidentally use npm format (with dashes):

data/lib/install/template.rb

@@ -18,7 +18,7 @@ install_dir = File.expand_path(File.dirname(__FILE__))
 # Installation strategy:
 # - USE_BABEL_PACKAGES installs both babel AND swc for compatibility
 # - Otherwise install only the specified transpiler
-if ENV["USE_BABEL_PACKAGES"] == "true" || ENV["USE_BABEL_PACKAGES"] == "1"
+if Shakapacker::Install::Env.truthy_env?("USE_BABEL_PACKAGES")
   @transpiler_to_install = "babel"
   @install_swc_compat_packages = true
   say "📦 Installing Babel packages (USE_BABEL_PACKAGES is set)", :yellow
@@ -52,7 +52,7 @@ end
 # Detect TypeScript usage
 # Auto-detect from tsconfig.json or explicit via SHAKAPACKER_USE_TYPESCRIPT env var
 @use_typescript = File.exist?(Rails.root.join("tsconfig.json")) ||
-  ENV["SHAKAPACKER_USE_TYPESCRIPT"] == "true"
+  Shakapacker::Install::Env.truthy_env?("SHAKAPACKER_USE_TYPESCRIPT")
 assets_bundler = ENV["SHAKAPACKER_ASSETS_BUNDLER"] || "webpack"
 config_extension = @use_typescript ? "ts" : "js"
 
@@ -225,7 +225,7 @@ Dir.chdir(Rails.root) do
 
   # Inline fetch_peer_dependencies and fetch_common_dependencies
   peers = PackageJson.read(install_dir).fetch(ENV["SHAKAPACKER_ASSETS_BUNDLER"] || "webpack")
-  common_deps = ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read(install_dir).fetch("common")
+  common_deps = Shakapacker::Install::Env.truthy_env?("SKIP_COMMON_LOADERS") ? {} : PackageJson.read(install_dir).fetch("common")
   peers = peers.merge(common_deps)
 
   # Add transpiler-specific dependencies based on detected/configured transpiler

data/lib/shakapacker/utils/version_syntax_converter.rb

@@ -17,7 +17,7 @@ module Shakapacker
                   .tr("-", ".")
                   .strip
                   .match(/(\d.*)/)
-        match.present? ? match[0] : nil
+        match ? match[0] : nil
       end
     end
   end

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.6.0.rc.0".freeze
+  VERSION = "9.6.0.rc.2".freeze
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.6.0-rc.0",
+  "version": "9.6.0-rc.2",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {