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) is materialized into a real file during the build so the File.basename(__FILE__) dual-boot trick works deterministically across Bundler versions. The repo keeps the symlink for the developer workflow.

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
   

   (image placeholder: buildpacks panel showing the new branch URL)

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

   (image placeholder: config vars panel)

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

   (image placeholder: overview showing BUNDLE_GEMFILE)

5. Trigger a deploy (push to the Heroku remote, or use Deploy → Manual deploy for GitHub-connected apps). The build log should include the line Materializing Gemfile.next symlink -> Gemfile (only if your app uses a Gemfile.next symlink) and then 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 without rebuilding from scratch:

   • heroku config:unset BUNDLE_GEMFILE -a <app>
   • heroku repo:purge_cache -a <app>
   • Redeploy. The buildpack behaves like stock heroku/ruby again and installs Gemfile.lock.

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
Symlink to real file materializer	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]

Stop it failing in our fork.

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