Add BUNDLE_GEMFILE-aware dual-boot support (rebased on v359)

[JuanVqz]

Summary

Adds dual-boot (next_rails) support on top of upstream v359. The buildpack reads the BUNDLE_GEMFILE env var (typically a Heroku config var) to decide which Gemfile drives the build. When BUNDLE_GEMFILE is unset, the buildpack behaves like stock heroku/ruby, making this a drop-in replacement.

Concretely:

• BUNDLE_GEMFILE unset → uses Gemfile and Gemfile.lock (default Heroku behavior).
• BUNDLE_GEMFILE=Gemfile.next → uses Gemfile.next and Gemfile.next.lock for the build, including bundler/ruby version detection, bundle install, bundle clean, bundle list, rake task detection, and runtime dyno boot.

A Gemfile.next that is a symlink to Gemfile (the common next_rails setup) works as-is: Bundler does not resolve the symlink, so File.basename(__FILE__) and the lockfile name both resolve to Gemfile.next. Verified across Bundler 2.1.4, 2.5.17, 2.5.22, 2.6.6, and 4.0.9. No symlink materialization is needed.

⚠️ Known limitation: switching BUNDLE_GEMFILE needs a rebuild, not just a config change

Heroku triggers a re-release but not a rebuild when a config var changes, and the build is what installs gems. So flipping BUNDLE_GEMFILE alone never installs the other Rails version's gems.

If an app built with Rails 6.1 has its BUNDLE_GEMFILE changed to Gemfile.next (Rails 7.0) without a redeploy, and it has a release: command in its Procfile, the release phase runs against Rails 7.0 whose gems are not in the slug, so it fails and Heroku reverts the config var. In the latest version of this fork the re-release no longer fails, but the change is not applied at runtime either, so Heroku reports the var changed while the app keeps running the previous version.

Always change BUNDLE_GEMFILE and then deploy, so the correct gems are installed at build time. This is documented at the top of the README.

Deployment steps

1. Make sure your app boots locally with BUNDLE_GEMFILE=Gemfile.next bundle exec rails -v showing the next Rails version.
2. Point the app at this branch: heroku buildpacks:set https://github.com/fastruby/heroku-buildpack-ruby#use_gemfile_next_v359 -a <app>.
3. Set the config var: heroku config:set BUNDLE_GEMFILE=Gemfile.next -a <app>.
4. Purge cache (recommended on first switch): heroku repo:purge_cache -a <app> (requires heroku-repo plugin).
5. Deploy: git push heroku <branch>:main.
6. Verify: heroku run "bin/rails --version" -a <app> should show the next Rails version.

To flip back: heroku config:unset BUNDLE_GEMFILE -a <app> and redeploy.

QA notes

1. Pick a project that already has the dual-boot configured and running locally.

2. In Heroku, go to Settings → Buildpacks. Remove heroku/ruby (or any previous fork branch) and add:

   https://github.com/fastruby/heroku-buildpack-ruby#use_gemfile_next_v359
   

3. In Settings → Config Vars, add BUNDLE_GEMFILE with value Gemfile.next, then click Add. Heroku may take a moment to apply.

4. In the Overview tab, confirm the new config var is listed.

5. Trigger a deploy (push to the Heroku remote, or use Deploy → Manual deploy for GitHub-connected apps). The build log should install gems for Gemfile.next.lock.

6. Once deployed, verify the running version:

   heroku run "bin/rails --version" -a <app>
   # Rails 8.1.x
   
   heroku run "bash -c 'echo $BUNDLE_GEMFILE'" -a <app>
   # /app/Gemfile.next
   

7. To flip back to the current Gemfile:

   • heroku config:unset BUNDLE_GEMFILE -a <app>
   • Redeploy (this rebuilds and installs Gemfile.lock). The buildpack behaves like stock heroku/ruby again. A config-var change alone is not enough (see the known limitation above).

Comparison vs the previous fork branches

Aspect	add_gemfile_next_support (2024)	use_gemfile_next_v359 (this PR)
Base	v270-ish (2 years stale)	v359 (current upstream)
Selection	BUNDLE_GEMFILE env var	BUNDLE_GEMFILE, defaults to Gemfile
rake_env BUNDLE_GEMFILE injection	no	yes
initialize_env before lockfile read	no (bug)	yes (fixed)
Reads from user_env_hash	no	yes
Bundler 4 lockfile support	no (bootstrap 1.17.3)	yes (inherited from v359)

What changed upstream between v270 (Apr 2024) and v359 (May 2026)

The rebase brings in 89 releases of fixes and new features. Highlights relevant to Ruby/Rails/bundler:

Bundler

• v333: Bundler 4.0 support (apps with BUNDLED WITH 4.0.x now receive Bundler 4.0).
• v341: Bundler version installed now matches BUNDLED WITH exactly. Previously the buildpack mapped to a "known good" version (e.g. 2.7.x would always install 2.7.2).
• v340: Bundler is now installed via gem install bundler instead of being pre-built and downloaded from S3.
• v346: Default bundler version bumped from 2.3.25 to 2.5.23. Ruby's stdlib bundler takes precedence when greater.
• v330: Supports BUNDLED WITH written with 2-space indent (newer bundler format).
• v326: Default 2.6.x → 2.6.9, 2.7.x → 2.7.2.

Ruby

• v338: Ruby 4.0.0 available. Subsequent: 4.0.1 (v343), 4.0.2 (v352), 4.0.3 (v357), 4.0.5 (v359).
• v336: Ruby 3.4.8. v351: 3.4.9.
• v344: Ruby 3.2.10. v355: 3.2.11.
• v354: Ruby 3.3.11. v327: 3.3.10. v323: 3.4.7. v276: 3.3.4.
• v332 / v339: Ruby version is now read directly from Gemfile.lock instead of being detected by running bundle platform --ruby. As a result, Ruby is now installed before Bundler.

Stack and platform

• v353: heroku-26 stack support.
• v345: Default Node.js version is now 24.13.0.
• v348: S3 downloads use dual-stack (IPv6) endpoints; fix for invalid DATABASE_URL when adapter is unknown.
• v322: Sets PUMA_PERSISTENT_TIMEOUT=95 to match Router 2.0 recommendations. Warns on Puma < 7.0.0, errors on Puma 7.0.0 to 7.0.2.

Removed / cleaned up

• v277: Stopped bundling bootstrap Ruby for each stack inside the buildpack archive.

Net effect for this PR

• We no longer fight a stale bootstrap Bundler 1.17.3 to read modern lockfiles.
• Bundler 4 lockfiles deploy without manual downgrade.
• The buildpack reads Ruby version directly from Gemfile.lock (or in our case Gemfile.next.lock), so the dual-boot wiring threads through cleanly without needing to reproduce the old bundle platform --ruby shell-out.

[JuanVqz]

Heroku passes user config vars to buildpacks via a directory of files (one file per var), not as actual ENV entries. The path to that dir is ARGV[2] in ruby_compile.rb.
Until LanguagePack::ShellHelpers.initialize_env(ARGV[2]) runs, that data isn't loaded anywhere.

Sequence before our fix:

gemfile_lock = LanguagePack.gemfile_lock(...)   # reads ENV["BUNDLE_GEMFILE"] → ""
Dir.chdir(app_path)
LanguagePack::ShellHelpers.initialize_env(...)  # now user_env_hash["BUNDLE_GEMFILE"] = "Gemfile.next"

LanguagePack.gemfile_name (which gemfile_lock calls via lockfile_name) reads:

  ENV["BUNDLE_GEMFILE"]                            # empty, Heroku doesn't set it in ENV
  || LanguagePack::ShellHelpers.user_env_hash[..]  # empty too, initialize_env hasn't run yet
  || "Gemfile"                                     # falls through to default

So it picked Gemfile.lock. The bundler/Ruby version detection then used the wrong lockfile, and build_bundler later built against Gemfile. Meanwhile bundle list (called with user_env: true) read user_env_hash["BUNDLE_GEMFILE"] = Gemfile.next and tried to verify gems from Gemfile.next.lock which had never been installed. That's the exact mismatch the failed build exposed.

After moving the line below initialize_env, user_env_hash is populated first, gemfile_name resolves to Gemfile.next, and every later phase agrees on the same lockfile.

[JuanVqz]

@arielj are we going to merge this PR or keep it as the previous version? if so, we need to update this to main or probably just the URL will pickup the default branch.

[JuanVqz]

@arielj, I want your opinion on the release process. AI suggested 3 options:

Option A: rebase a thin patch per upstream release (recommended)

• Fork main mirrors upstream/main exactly. Never commit fork code to it.
• Dual-boot lives as a handful of commits on a branch, rebased on top of upstream when you sync.
• This is literally what you're already doing: use_gemfile_next_v359 = v359 + patch.

Sync flow:

git fetch upstream
git checkout main && git merge --ff-only upstream/main && git push origin main
git checkout gemfile-next && git rebase main
# resolve conflicts (only in the ~4 files you touch), then:
git push --force-with-lease origin gemfile-next

• Pro: clean linear history, tiny conflict surface, easy to see "our patch vs upstream," easy to re-cut per version.
• Con: force-push each sync (fine, nobody depends on commit stability, only the buildpack URL needs latest).

Option B: merge upstream into a long-lived branch

Keep one permanent gemfile-next branch, git merge upstream/main into it each sync.

• Pro: no force-push, conflicts resolved incrementally.
• Con: merge-commit noise, harder to isolate "just our change," README/CHANGELOG churn every merge.

Option C: automate the sync

A scheduled GitHub Action (or local bin/sync-upstream script) that fetches upstream, fast-forwards main, rebases the patch, opens a PR.

• Pro: hands-off, regular.
• Con: you just removed all workflows; conflicts still need a human. Better as a local script than a re-added Action.

My recommendation

Option A, plus a small local bin/sync-upstream helper so the rebase dance is one command. It matches your existing per-version workflow, keeps the patch reviewable, and the tiny footprint means rebase
conflicts are rare and localized. Drop the version suffix and use a stable branch name like gemfile-next so the buildpack URL never changes; tag v359, v360 etc. at each sync if you want pinnable points.

[arielj]

I think we should do option A, main branch being the latest official buildpack code + some patches, and we tag versions so they can be used in heroku

[arielj]

not sure if these 2 lines are needed, or maybe they can be confusing

someone using this version might not understand what's this referring to since they won't experience the failure/revert

I think that we can say something like...

When changing an environment variable, Heroku will trigger a re-release. In some cases, if the re-release fails, Heroku might revert the value to the previous one. If that happens for your app, we recommend using that supports deploying the next version without the use of the BUNDLE_GEMFILE variable.

[JuanVqz]

Updated, is this any better?