Bundler 4 roadmap

[deivid-rodriguez]

We have a plan to release Bundler 4 by the end of this year. This is a placeholder ticket to explain the motivations and what we expect to include in this major release.

Context

Bundler currently keeps a branched code base, where there are a number of feature flags that will be enabled only once a major version is released, because they are considered breaking changes.

However, a real major version has not happened for many years. We did release Bundler 2 back in 2019, but that just delayed real breaking changes to future Bundler 3 and only dropped support for old rubies. So, in practice, these features have remained hidden for a long time and our users don’t benefit from them. This also causes maintenance overhead, a slower CI (due to the extra Bundler 2 vs Bundler 3 dimension), makes things harder for contributors, and makes an already complex code base more complex.

The goal of this project is to remove the above tech debt and make all currently hidden features/changes/improvements generally available. We want to study each of these feature flags separately and evaluate a number of things in order to make them releasable:

• Whether they still make sense in 2025 or should be cancelled instead.
• Whether they need any additional changes or it is only a matter of "toggling the switch".
• Whether a particular migration/deprecation path is needed.
• Etc.

Naming

RubyGems and Bundler have been released in lockstep for a while now. However, their version numbers are different (Bundler is currently at 2.x.y, while RubyGems is at 3.x.y), which makes things a bit weird.

I think it is a good time to take the chance and finally sync version numbers of Bundler & RubyGems, hence the idea of naming this major release "Bundler 4", skipping Bundler 3. That way, Bundler 4 & RubyGems 4 can be released together and their versions can stay synced going forward.

⚠ NOTE: RubyGems 4 roadmap will be tracked separately, although there are not many breaking changes pending there.

Changes

The following is the list of feature flags that will be switched on by default in Bundler 4:

• Enable default_install_uses_path by default #8653
• Enable allow_offline_install by default #8654
• Enable auto_clean_without_path by default #8655
• Enable cache_all by default #8656
• Enable forget_cli_options by default #8657
• Enable global_gem_cache by default #8658
• Enable lockfile_checksums by default #8659
• Enable path_relative_to_cwd by default #8660
• Enable print_only_version_number by default #8661
• Enable setup_makes_kernel_gem_public by default #8662
• Set default_cli_command to cli_help by default #8786

Deprecated features that will get removed

In addition to all the feature flags, there's a decent amount of deprecated functionality that will get completely removed.

All of those are detailed in this document. It's a bit old now, so needs to be reviewed and probably some missing stuff added to it.

I'll be compiling a reviewed list of these removed features here, too:

• Remove deprecated bundle viz and bundle inject commands #8923
• Remove deprecated Bundler.*clean*, and Bundler.environment helpers #8924
• Remove implementation of deployment, capistrano and vlad entrypoints #8957
• Completely remove --rubocop flag to bundle gem, and related configuration #8967
• Remove support for multiple global sources in Gemfile & lockfile #8968
• Completely forbid passing --ext to bundle gem without a value #8976
• Make bundle remove --install raise an error #8977
• Make bundle install --binstubs raise an error #8978
• Make --local-git flag to bundle plugin install raise an error #8979
• Make bundle show --outdated raise an error #8980

Release plan

• Phase 1. Prepare and get some basic community agreement on all of the above changes.
• Phase 2. Release some CLI flag or configuration like --mode 4 or something, so that folks can easily test the future major release (by mid-year, approximately).
• Phase 3. Get Bundler 4 out (by beginning of December).
• Phase 4. Refine release and fix regressions so that we can include some Bundler 4.0.x version with Ruby 3.5 (25th of December).

Non goals

• Further unification of RubyGems & Bundler, rather than syncing version numbers is not a goal of this project.
• Any additional breaking changes or big features should be discussed separately, and if approved will be released when ready in the next major version after they are completed, not necessarily Bundler 4.

[hsbt]

This also causes maintenance overhead, a slower CI (due to the extra Bundler 2 vs Bundler 3 dimension), makes things harder for contributors, and makes an already complex code base more complex.

+1

Phase 2. Release some CLI flag or configuration like --mode 4 or something, so that folks can easily test the future major release (by mid-year, approximately).

The above changes will be introduced at bundler-2.6.x? I think we can ship that with bundler-2.7.0. How about this?

[deivid-rodriguez]

The above changes will be introduced at bundler-2.6.x? I think we can ship that with bundler-2.7.0. How about this?

That was my initial idea, yeah, because that's what we've been doing until now (one minor/major bump per year). But maybe we can do RubyGems 3.7.0 and Bundler 2.7.0 by mid-year this one time, and then release RubyGems 4 and Bundler 4 in December.

[hsbt]

Thanks. I'm +1 for the above release plan that we will release 2.7.x or 3.0.x at mid-year and 4.0 at beginning of December.

[sandstrom]

Flags passed to bundle install that relied on being remembered across invocations have been deprecated.

Great that this behavior is being dropped! 🎉

[rubyFeedback]

Syncing version numbers may indeed simplify things a bit, so people don't get confused. Perhaps a future roadmap could integrate both into one unified project; may not be worth the time investment, but I think if it were possible, it would lessen the confusion people would have in regards to both. (Namespace could be "aliased", e. g. Gem.some_method() could be the same as Bundler.some_method() - but, as said, this may require too much work. Either way it could make sense to unify tasks for one shared / co-shared version whenever it is the same. Things such as downloading, extracting, installing etc...)

[deivid-rodriguez]

I added one more setting I forgot to the list, see #8786, in case someone wants to chime in in there.

[voxik]

RubyGems 4 roadmap will be tracked separately

Just wonder, is this tracked somewhere already?

[deivid-rodriguez]

Not yet, but I don't think there are big changes planned, just take the chance to completely remove what's already deprecated.

[deivid-rodriguez]

Just some heads up that Phase 2 of this project has been completed and Bundler 2.7.0 has been released, featuring a simulate_version setting that allows configuring Bundler to behave like Bundler 4 will behave, through bundle config simulate_version 4.

[voxik]

I just wanted to make sure this is considered:

https://github.com/rubygems/rubygems/blob/5d331faa39124fe17364a249478c7fbd7880d2d4/lib/rubygems/config_file.rb#L50-L51

Because similar change was forgotten when releasing 3.0

[jonbarlo]

hi @voxik and @deivid-rodriguez i raised a PR with this last change @voxik mentioned just in case it helps, whenever you have a chance would you mind taking a look and letting me know? not sure if we wanted a warning but i added it.

Thanks!

[jonbarlo]

@deivid-rodriguez hi! i was wondering if i can help with these tasks?

#8653

#8654

#8655

let me know thanks!

[deivid-rodriguez]

I'd suggest that you focus instead on finalizing the multiple ongoing PRs that you already have opened!

[deivid-rodriguez]

In particular, let's start with #8886. That's also Bundler 4 related and almost ready to go!