Proposal: override DSL in Gemfile for managing version constraints

[hsbt]

Background

In the discussion around #9454, reviewers (including @byroot and @Edouard-chin) pointed out that BUNDLE_IGNORE_RUBY_UPPER_BOUNDS and BUNDLE_IGNORE_RUBYGEMS_UPPER_BOUNDS should be expressible in the Gemfile, not only via environment variables.

Around the same time, @byroot published The Missing Bundler Features arguing that Bundler lacks a way to override constraints imposed by upstream gems, and Shopify released bundler-ignore-dependency as a plugin that prototypes one form of the idea.

This proposal is an attempt to converge those threads into a single Gemfile-level DSL for the constraint-relaxation part of the problem. Aliasing, banning, and additive constraints are intentionally out of scope and deferred to separate discussions.

Proposed syntax

override <target>, <field>: <operation>, ...

• target is either :all (meaning every gemspec in the resolution graph) or a gem name string.
• field names which piece of metadata to operate on — currently one of version, required_ruby_version, or required_rubygems_version.
• operation is one of three values: a version spec string (absolute replacement), the symbol :ignore_upper (strip < and <= while keeping lower bounds), or nil (remove the constraint entirely). Multiple fields may be given in a single call.

source "https://rubygems.org"

# Strip upper bounds from required_ruby_version across every gemspec
override :all, required_ruby_version: :ignore_upper

# Replace every gemspec's required_ruby_version with "> 3"
# (rarely needed in practice, but supported for completeness)
override :all, required_ruby_version: "> 3"

# Drop required_rubygems_version entirely
override :all, required_rubygems_version: nil

# Force transitive rails resolution to >= 8.0
override "rails", version: ">= 8.0"

# Only strip upper bounds on nokogiri, keep lower bounds
override "nokogiri", version: :ignore_upper

# Multi-field in one call (recommended canonical form)
override "rails",
  version: ">= 8.0",
  required_ruby_version: :ignore_upper

gem "rails", "~> 8.0"

Semantics

A version string is an absolute replacement. The target's existing requirement is wholly replaced by the given spec, regardless of what the gemspec or the upstream gem asked for. This follows uv's wording: "Overrides are absolute — they completely replace constituent package requirements." :ignore_upper removes only < and <= from the existing requirement and preserves lower bounds; this is the common case of "stale upper bound on a new Ruby release". nil strips the constraint entirely.

The allowed combinations are:

target	field	operation
:all	required_ruby_version	string / :ignore_upper / nil
:all	required_rubygems_version	string / :ignore_upper / nil
"gem"	version	string / :ignore_upper / nil
"gem"	required_ruby_version	string / :ignore_upper / nil
"gem"	required_rubygems_version	string / :ignore_upper / nil

:all + version: is not allowed: a dependency version requirement only has meaning relative to a specific gem.

Validation rules

Condition	Behavior
:all combined with version:	ArgumentError
Same target across multiple statements with different fields	warn (encourage consolidation into one call)
Same target across multiple statements with the same field	ArgumentError
Multi-field call where any value is invalid	atomic error; no field is applied
Invalid value type (e.g. version: 123)	ArgumentError
Unknown field keyword	ArgumentError

The canonical form is one override call per target. Splitting across multiple statements is allowed but warned so that the intent stays in one place.

Supersedes #9454

This proposal supersedes #9454. The environment variables introduced there (BUNDLE_IGNORE_RUBY_UPPER_BOUNDS and BUNDLE_IGNORE_RUBYGEMS_UPPER_BOUNDS) are better expressed as Gemfile declarations:

• BUNDLE_IGNORE_RUBY_UPPER_BOUNDS=true → override :all, required_ruby_version: :ignore_upper
• BUNDLE_IGNORE_RUBYGEMS_UPPER_BOUNDS=true → override :all, required_rubygems_version: :ignore_upper

The reviewers' feedback on #9454 pointed out that this kind of configuration belongs in the Gemfile where the intent is visible to every developer on the project, not in an environment variable that silently changes behavior.

If this proposal is enough to their usecases, I will withdraw #9454.

Open questions

1. How should applied overrides be recorded in Gemfile.lock so that the lockfile alone is enough to reproduce resolution?
2. What should diagnostic output look like when a resolution failure is influenced by an override?

Prior art

• Add ignore_ruby_upper_bounds and ignore_rubygems_upper_bounds settings #9454 — the env-variable PR
• The Missing Bundler Features
• Shopify/bundler-ignore-dependency
• baweaver's block-scope sketch on Bluesky

[byroot]

Thanks a lot for tackling this @hsbt !

I'm not attached to any particular DSL, I think this one is flexible enough for most common use cases.

How should applied overrides be recorded in Gemfile.lock so that the lockfile alone is enough to reproduce resolution?

Is it even necessary? I'm not intimately familiar with Bundler's internal design, but it was my understanding that the Gemfile.lock is only there to precisely list the dependencies to install. Ideally constraints are only checked during resolution (bundle lock), and subsequent bundle install don't need to know about these at all.

What should diagnostic output look like when a resolution failure is influenced by an override?

So right now if resolution fails, for example:

source "https://rubygems.org"

gem "web-push", "3.1.0"
gem "signet", "0.17.0"

We get:

Because web-push >= 3.0.2 depends on jwt ~> 3.0
  and signet >= 0.8.0, < 0.21.0 depends on jwt >= 1.5, < 3.0,
  web-push >= 3.0.2 is incompatible with signet >= 0.8.0, < 0.21.0.
So, because Gemfile depends on web-push = 3.1.0
  and Gemfile depends on signet = 0.17.0,
  version solving has failed.

If one of the involved constraint was overridden we could ideally display a note of where the constraint override is, something like:

Because web-push >= 3.0.2 depends on jwt ~> 3.0 (overridden in Gemfile:12) 
  and signet >= 0.8.0, < 0.21.0 depends on jwt >= 1.5, < 3.0,
  web-push >= 3.0.2 is incompatible with signet >= 0.8.0, < 0.21.0.
So, because Gemfile depends on web-push = 3.1.0
  and Gemfile depends on signet = 0.17.0,
  version solving has failed.

[hsbt]

Ideally constraints are only checked during resolution (bundle lock), and subsequent bundle install don't need to know about these at all.

I thought it would be better to update conditions that ignore the upper version in the lockfile. However, as you commented, I think it's fine to keep the lockfile as it is and override the constraints during dependency resolution.

Regarding error messages, I plan to maintain the current state while also adding information about which constraints have been overridden.

[paracycle]

Are there plans to add support for completely ignoring a dependency, so that one can bring in a replacement that fulfills the same runtime API?

For example, suppose that I have forked the grpc gem and released my fork as ufuk-grpc to Rubygems.org, can I do the following?

override "grpc", ignore: true
gem "ufuk-grpc"

gem "some-gem-that-depends-on-grpc"

(not sure if ignore: true is the best name for it, but I am interested in if the behaviour will be supported or not)

If this is supported, I think this will need to be recorded in the lockfile.

[byroot]

I think this will need to be recorded in the lockfile.

Does it? Wouldn't it be done just by removing all references to that gem in the Gemfile.lock?

[paracycle]

@byroot Not sure, but since the listed dependencies of the some-gem-that-depends-on-grpc in the lockfile would not match the ones listed in the gemspec, I can imagine some confusion happening. I am also hazy on the details of how exactly the lockfile is used inside Bundler, though.