[ruby/rubygems] Document Phase 2 override DSL extensions in gemfile.5

Update the OVERRIDE section to cover the :all target, the
required_ruby_version / required_rubygems_version fields, and the
diagnostic shown on resolve failure.

https://github.com/ruby/rubygems/commit/ac90c83b1b

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2 files changed, 33 insertions, 11 deletions

diff --git a/lib/bundler/man/gemfile.5 b/lib/bundler/man/gemfile.5
index 0874bb5a4a..64e93c4b15 100644
--- a/lib/bundler/man/gemfile.5
+++ b/lib/bundler/man/gemfile.5
@@ -461,22 +461,24 @@ The \fBgemspec\fR method supports optional \fB:path\fR, \fB:glob\fR, \fB:name\fR
 .P
 When a \fBgemspec\fR dependency encounters version conflicts during resolution, the local version under development will always be selected \-\- even if there are remote versions that better match other requirements for the \fBgemspec\fR gem\.
 .SH "OVERRIDE"
-The \fBoverride\fR directive rewrites the version requirement on another gem before resolution runs\. It targets the common case where an upstream gem's published metadata is too narrow on the current project's machine \-\- a stale upper bound, an unwanted floor, or a transitive pin that has to be lifted\.
+The \fBoverride\fR directive rewrites a constraint on another gem before resolution runs\. It targets the common case where an upstream gem's published metadata is too narrow on the current project's machine \-\- a stale upper bound, an unwanted floor, or a transitive pin that has to be lifted\.
 .IP "" 4
 .nf
 override <target>, <field>: <operation>
 .fi
 .IP "" 0
 .P
-\fB<target>\fR is a gem name string\. \fB<field>\fR is \fBversion:\fR\. \fB<operation>\fR is one of:
+\fB<target>\fR is a gem name string or \fB:all\fR\. \fB<field>\fR is one of \fBversion:\fR, \fBrequired_ruby_version:\fR, or \fBrequired_rubygems_version:\fR\. \fB<operation>\fR is one of:
 .IP "\(bu" 4
-a version requirement string (e\.g\. \fB">= 8\.0"\fR), which \fBreplaces\fR the target's version requirement absolutely\. The original requirement, both direct and transitive, is discarded in favour of the override\.
+a version requirement string (e\.g\. \fB">= 8\.0"\fR), which \fBreplaces\fR the target's requirement absolutely\. The original requirement, both direct and transitive, is discarded in favour of the override\.
 .IP "\(bu" 4
 \fB:ignore_upper\fR, which removes upper\-bound operators (\fB<\fR and \fB<=\fR) from the existing requirement and folds \fB~>\fR into its lower bound (\fB~> 1\.5\fR becomes \fB>= 1\.5\fR)\. Other operators, including \fB!=\fR, are preserved\.
 .IP "\(bu" 4
 \fBnil\fR, which collapses the requirement to \fB>= 0\fR (no constraint at all)\.
 .IP "" 0
 .P
+\fB:all\fR only applies to \fBrequired_ruby_version:\fR and \fBrequired_rubygems_version:\fR\. A per\-gem override on the same field takes precedence over an \fB:all\fR override\. \fB:all + version:\fR is rejected: version requirements only make sense per gem\.
+.P
 Multiple \fBoverride\fR calls for distinct targets are allowed; declaring the same \fBtarget\fR and \fBfield\fR twice is an error\.
 .IP "" 4
 .nf
@@ -491,11 +493,17 @@ override "nokogiri", version: :ignore_upper
 # Drop the version pin on legacy entirely\.
 override "legacy", version: nil
 
+# Loosen every gem's required_ruby_version upper bound\.
+override :all, required_ruby_version: :ignore_upper
+
+# Override one specific gem's required_rubygems_version\.
+override "tricky", required_rubygems_version: nil
+
 gem "rails", "~> 7\.0"
 .fi
 .IP "" 0
 .P
-The override only affects resolution; \fBGemfile\.lock\fR continues to reflect the resolved versions, not the rewritten requirements\.
+The override only affects resolution and the install\-time Ruby/RubyGems compatibility checks; \fBGemfile\.lock\fR continues to reflect the resolved versions, not the rewritten requirements\. When resolution still fails, Bundler appends the active overrides (with their Gemfile location) to the error message so it is clear which override shaped the constraint set\.
 .SH "SOURCE PRIORITY"
 When attempting to locate a gem to satisfy a gem requirement, bundler uses the following priority order:
 .IP "1." 4
diff --git a/lib/bundler/man/gemfile.5.ronn b/lib/bundler/man/gemfile.5.ronn
index 1779fc0a01..69fef90654 100644
--- a/lib/bundler/man/gemfile.5.ronn
+++ b/lib/bundler/man/gemfile.5.ronn
@@ -543,24 +543,29 @@ remote versions that better match other requirements for the `gemspec` gem.
 
 ## OVERRIDE
 
-The `override` directive rewrites the version requirement on another gem
-before resolution runs. It targets the common case where an upstream gem's
+The `override` directive rewrites a constraint on another gem before
+resolution runs. It targets the common case where an upstream gem's
 published metadata is too narrow on the current project's machine -- a stale
 upper bound, an unwanted floor, or a transitive pin that has to be lifted.
 
     override <target>, <field>: <operation>
 
-`<target>` is a gem name string. `<field>` is `version:`. `<operation>` is
+`<target>` is a gem name string or `:all`. `<field>` is one of `version:`,
+`required_ruby_version:`, or `required_rubygems_version:`. `<operation>` is
 one of:
 
   * a version requirement string (e.g. `">= 8.0"`), which **replaces** the
-    target's version requirement absolutely. The original requirement, both
-    direct and transitive, is discarded in favour of the override.
+    target's requirement absolutely. The original requirement, both direct
+    and transitive, is discarded in favour of the override.
   * `:ignore_upper`, which removes upper-bound operators (`<` and `<=`) from
     the existing requirement and folds `~>` into its lower bound (`~> 1.5`
     becomes `>= 1.5`). Other operators, including `!=`, are preserved.
   * `nil`, which collapses the requirement to `>= 0` (no constraint at all).
 
+`:all` only applies to `required_ruby_version:` and `required_rubygems_version:`.
+A per-gem override on the same field takes precedence over an `:all` override.
+`:all + version:` is rejected: version requirements only make sense per gem.
+
 Multiple `override` calls for distinct targets are allowed; declaring the
 same `target` and `field` twice is an error.
 
@@ -575,10 +580,19 @@ same `target` and `field` twice is an error.
     # Drop the version pin on legacy entirely.
     override "legacy", version: nil
 
+    # Loosen every gem's required_ruby_version upper bound.
+    override :all, required_ruby_version: :ignore_upper
+
+    # Override one specific gem's required_rubygems_version.
+    override "tricky", required_rubygems_version: nil
+
     gem "rails", "~> 7.0"
 
-The override only affects resolution; `Gemfile.lock` continues to reflect
-the resolved versions, not the rewritten requirements.
+The override only affects resolution and the install-time Ruby/RubyGems
+compatibility checks; `Gemfile.lock` continues to reflect the resolved
+versions, not the rewritten requirements. When resolution still fails,
+Bundler appends the active overrides (with their Gemfile location) to the
+error message so it is clear which override shaped the constraint set.
 
 ## SOURCE PRIORITY