Walkthrough

The release process was reorganized to update lockfiles earlier in the workflow. Documentation and the Rake task were modified to run yarn and npm installs as a pre-release step in the spec/dummy directory, removing subsequent commit and push logic that previously handled detected lockfile changes.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Whiskers twitching with delight,
Lockfiles sync both left and right,
Before the release, not after the fact,
Our Yarn and npm now perfectly packed! 🧵

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This PR fixes a CI failure caused by a stale spec/dummy/Gemfile.lock (referencing 9.6.0.rc.3 instead of 9.6.0) and corrects the root cause in the release script by moving the spec/dummy bundle install to run before release-it, so the lockfile update is captured in the release commit via release-it's git add ..

• Moves bundle install for spec/dummy to before the release-it invocation, ensuring the Gemfile.lock is part of the release commit rather than a stale follow-up
• Removes the old post-release block that attempted (and failed) to detect and commit changed lockfiles after the release had already been pushed
• Updates spec/dummy/Gemfile.lock from shakapacker 9.6.0.rc.3 → 9.6.0 to fix the immediate bundler frozen-mode error
• The npm install step for spec/dummy that previously ran post-release has been removed entirely — worth confirming this is intentional given that yarn.lock / package-lock.json are no longer updated during the release flow

Confidence Score: 4/5

• Safe to merge — the fix is logically correct and the immediate CI failure is resolved; one minor open question around the dropped npm lockfile update.
• The core change is straightforward and well-reasoned: running bundle install in spec/dummy before release-it ensures the Gemfile.lock is included in the release commit. The removal of the post-release npm lockfile update and follow-up commit logic simplifies the script and eliminates the race condition. The only uncertainty is whether the npm lockfiles (yarn.lock, package-lock.json) in spec/dummy need to be kept current during release — the old code attempted to do this, and the new code silently drops it.
• rakelib/release.rake — confirm the intentional removal of npm install for spec/dummy

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant R as release.rake
    participant Root as Root Directory
    participant Dummy as spec/dummy
    participant RI as release-it
    participant RG as RubyGems

    Note over R: perform_release()

    R->>Root: gem bump --no-commit
    R->>Root: bundle install (updates root Gemfile.lock)
    Note over Dummy: ✅ Moved here (was after release-it)
    R->>Dummy: bundle install (updates spec/dummy/Gemfile.lock)
    R->>RI: release-it (git add . → commits ALL changes incl. lockfiles, tags, pushes, npm publish)
    R->>RG: gem release

    Note over R: ❌ Removed: post-release bundle/npm install + follow-up commit

_{Last reviewed commit: 43194a9}

Review: The fix is well-reasoned. Moving spec/dummy bundle install before release-it is the correct approach — it ensures the lockfile update is picked up by release-it's git add . and included in the release commit. Removes the post-release follow-up commit logic which was a workaround rather than a fix. Three notes: (1) npm install for spec/dummy is dropped entirely — since spec/dummy uses a yalc local link for shakapacker rather than a versioned npm reference, this is likely fine, but worth confirming the yarn.lock and package-lock.json in spec/dummy no longer need to be updated during releases. (2) The fix relies on release-it's default git add . behavior; no .release-it.json was found so defaults apply, but worth verifying git.addUntrackedFiles is not overridden. (3) The new bundle install runs unconditionally during dry runs too — consistent with root bundle install behavior, low concern.

Releasing Shakapacker

This guide is for Shakapacker maintainers who need to publish a new release.

Prerequisites

1. Install required tools:

   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:

   • npm: You must be a collaborator on the shakapacker npm package
   • RubyGems: You must be an owner of the shakapacker gem

3. Enable 2FA on both platforms:

   • 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. Update the Changelog

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. 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 simplest way to release is with no arguments — the task reads the version from CHANGELOG.md:

# 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

# 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]"

# 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. 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)
4. Publishes to npm:
   • Prompts for npm OTP (2FA code)
   • Creates git tag
   • Pushes to GitHub
5. Publishes to RubyGems:
   • Prompts for RubyGems OTP (2FA code)
6. Updates spec/dummy lockfiles:
   • Runs bundle install to update Gemfile.lock
   • Runs yarn install to refresh the Yarn-managed dummy app lockfile
   • Runs npm install to keep package-lock.json in sync for npm compatibility/testing
7. Commits and pushes lockfile changes automatically
8. Creates GitHub release from CHANGELOG.md (if the matching section exists)

4. Version Format

Important: Use Ruby gem version format (no dashes):

• ✅ Correct: 9.1.0, 9.2.0.beta.1, 9.0.0.rc.2
• ❌ Wrong: 9.1.0-beta.1, 9.0.0-rc.2

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:

# Regular release
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

# Release candidate
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

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. 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

1. Verify the release on:

   • npm
   • RubyGems
   • GitHub releases

2. Check that the lockfile commit was pushed:

   git log --oneline -5
   # Should see "Update spec/dummy lockfiles after release"

3. Announce the release (if appropriate):

   • Post in relevant Slack/Discord channels
   • 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:

# 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

If you see uncommitted changes to lockfiles after a release, this means:

1. The release was successful but the lockfile commit step may have failed
2. Solution: Manually commit these files:

   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
   git commit -m 'Update spec/dummy lockfiles after release'
   git push

Failed npm or RubyGems Publish

If publishing fails partway through:

1. Check which step failed (npm or RubyGems)
2. If npm failed: Fix the issue and manually run npm publish
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:

   bundle exec rake "sync_github_release[<gem_version>]"

Wrong Version Format

If you accidentally use npm format (with dashes):

1. The gem will be created with an invalid version
2. Solution: Don't push the changes, reset your branch:

   git reset --hard HEAD

3. Re-run with correct Ruby gem format

Manual Release Steps

If you need to release manually (not recommended):

1. Bump version:

   gem bump --version 9.1.0
   bundle install

2. Publish to npm:

   release-it 9.1.0 --npm.publish

3. Publish to RubyGems:

   gem release

4. Update lockfiles:

   cd spec/dummy
   bundle install
   npm install
   cd ../..
   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
   git commit -m 'Update spec/dummy lockfiles after release'
   git push

Questions?

If you encounter issues not covered here, please:

1. Check the CONTRIBUTING.md guide
2. Ask in the maintainers channel
3. Update this documentation for future releases

Review

The fix correctly identifies and addresses the root cause: spec/dummy lockfile updates were happening after release-it had already committed and pushed, so they ended up as orphaned changes. Moving them before release-it is the right approach.

Two issues worth addressing:

1. docs/releasing.md is now inaccurate

The documentation still describes the old flow. Step 6 places lockfile updates after RubyGems publish, but in the updated code they now happen before release-it (before npm publish, tagging, and git push). Step 7 says 'Commits and pushes lockfile changes automatically' but that entire code path was deleted -- the lockfiles are now committed as part of the release-it release commit, not in a separate follow-up commit. Leaving step 7 in the docs will confuse the next person reading the release process.

2. Progress logging removed without replacement

The old code wrapped the spec/dummy install step with ZZZZ... banner separators, making it easy to spot in release logs. The new code runs the three install commands silently inline. A brief puts before them (e.g. 'Updating spec/dummy lockfiles...') would help maintainers follow along during a real release.