rubygems-update 4.0.21 → 4.1.0.beta1

data/lib/rubygems/vendor/securerandom/lib/securerandom.rb

@@ -38,6 +38,10 @@ require 'random/formatter'
 # If a secure random number generator is not available,
 # +NotImplementedError+ is raised.
 
+# Skip reloading when an identical copy (e.g. the one shipped inside the Bundler
+# gem) was already required from a different path, to avoid redefinition warnings.
+return if defined?(Gem::SecureRandom::VERSION)
+
 module Gem::SecureRandom
 
   # The version

data/lib/rubygems/vendor/timeout/lib/timeout.rb

@@ -20,9 +20,9 @@
 
 module Gem::Timeout
   # The version
-  VERSION = "0.4.4"
+  VERSION = "0.6.1"
 
-  # Internal error raised to when a timeout is triggered.
+  # Internal exception raised to when a timeout is triggered.
   class ExitException < Exception
     def exception(*) # :nodoc:
       self
@@ -44,12 +44,101 @@ module Gem::Timeout
   end
 
   # :stopdoc:
-  CONDVAR = ConditionVariable.new
-  QUEUE = Queue.new
-  QUEUE_MUTEX = Mutex.new
-  TIMEOUT_THREAD_MUTEX = Mutex.new
-  @timeout_thread = nil
-  private_constant :CONDVAR, :QUEUE, :QUEUE_MUTEX, :TIMEOUT_THREAD_MUTEX
+
+  # We keep a private reference so that time mocking libraries won't break Gem::Timeout.
+  GET_TIME = Process.method(:clock_gettime)
+  if defined?(Ractor.make_shareable)
+    # Ractor.make_shareable(Method) only works on Ruby 4+
+    Ractor.make_shareable(GET_TIME) rescue nil
+  end
+  private_constant :GET_TIME
+
+  class State
+    def initialize
+      @condvar = ConditionVariable.new
+      @queue = Queue.new
+      @queue_mutex = Mutex.new
+
+      @timeout_thread = nil
+      @timeout_thread_mutex = Mutex.new
+    end
+
+    if defined?(Ractor.store_if_absent) && defined?(Ractor.shareable?) && Ractor.shareable?(GET_TIME)
+      # Ractor support if
+      # 1. Ractor.store_if_absent is available
+      # 2. Method object can be shareable (4.0~)
+      def self.instance
+        Ractor.store_if_absent :timeout_gem_state do
+          State.new
+        end
+      end
+    else
+      GLOBAL_STATE = State.new
+
+      def self.instance
+        GLOBAL_STATE
+      end
+    end
+
+    def create_timeout_thread
+      # Threads unexpectedly inherit the interrupt mask: https://github.com/ruby/timeout/issues/41
+      # So reset the interrupt mask to the default one for the timeout thread
+      Thread.handle_interrupt(Object => :immediate) do
+        watcher = Thread.new do
+          requests = []
+          while true
+            until @queue.empty? and !requests.empty? # wait to have at least one request
+              req = @queue.pop
+              requests << req unless req.done?
+            end
+            closest_deadline = requests.min_by(&:deadline).deadline
+
+            now = 0.0
+            @queue_mutex.synchronize do
+              while (now = GET_TIME.call(Process::CLOCK_MONOTONIC)) < closest_deadline and @queue.empty?
+                @condvar.wait(@queue_mutex, closest_deadline - now)
+              end
+            end
+
+            requests.each do |req|
+              req.interrupt if req.expired?(now)
+            end
+            requests.reject!(&:done?)
+          end
+        end
+
+        if !watcher.group.enclosed? && (!defined?(Ractor.main?) || Ractor.main?)
+          ThreadGroup::Default.add(watcher)
+        end
+
+        watcher.name = "Gem::Timeout stdlib thread"
+        watcher.thread_variable_set(:"\0__detached_thread__", true)
+        watcher
+      end
+    end
+
+    def ensure_timeout_thread_created
+      unless @timeout_thread&.alive?
+        # If the Mutex is already owned we are in a signal handler.
+        # In that case, just return and let the main thread create the Gem::Timeout thread.
+        return if @timeout_thread_mutex.owned?
+
+        Sync.synchronize @timeout_thread_mutex do
+          unless @timeout_thread&.alive?
+            @timeout_thread = create_timeout_thread
+          end
+        end
+      end
+    end
+
+    def add_request(request)
+      Sync.synchronize @queue_mutex do
+        @queue << request
+        @condvar.signal
+      end
+    end
+  end
+  private_constant :State
 
   class Request
     attr_reader :deadline
@@ -64,6 +153,7 @@ module Gem::Timeout
       @done = false # protected by @mutex
     end
 
+    # Only called by the timeout thread, so does not need Sync.synchronize
     def done?
       @mutex.synchronize do
         @done
@@ -74,6 +164,7 @@ module Gem::Timeout
       now >= @deadline
     end
 
+    # Only called by the timeout thread, so does not need Sync.synchronize
     def interrupt
       @mutex.synchronize do
         unless @done
@@ -84,64 +175,36 @@ module Gem::Timeout
     end
 
     def finished
-      @mutex.synchronize do
+      Sync.synchronize @mutex do
         @done = true
       end
     end
   end
   private_constant :Request
 
-  def self.create_timeout_thread
-    watcher = Thread.new do
-      requests = []
-      while true
-        until QUEUE.empty? and !requests.empty? # wait to have at least one request
-          req = QUEUE.pop
-          requests << req unless req.done?
-        end
-        closest_deadline = requests.min_by(&:deadline).deadline
-
-        now = 0.0
-        QUEUE_MUTEX.synchronize do
-          while (now = GET_TIME.call(Process::CLOCK_MONOTONIC)) < closest_deadline and QUEUE.empty?
-            CONDVAR.wait(QUEUE_MUTEX, closest_deadline - now)
-          end
-        end
-
-        requests.each do |req|
-          req.interrupt if req.expired?(now)
-        end
-        requests.reject!(&:done?)
-      end
-    end
-    ThreadGroup::Default.add(watcher) unless watcher.group.enclosed?
-    watcher.name = "Gem::Timeout stdlib thread"
-    watcher.thread_variable_set(:"\0__detached_thread__", true)
-    watcher
-  end
-  private_class_method :create_timeout_thread
-
-  def self.ensure_timeout_thread_created
-    unless @timeout_thread and @timeout_thread.alive?
-      # If the Mutex is already owned we are in a signal handler.
-      # In that case, just return and let the main thread create the @timeout_thread.
-      return if TIMEOUT_THREAD_MUTEX.owned?
-      TIMEOUT_THREAD_MUTEX.synchronize do
-        unless @timeout_thread and @timeout_thread.alive?
-          @timeout_thread = create_timeout_thread
-        end
+  module Sync
+    # Calls mutex.synchronize(&block) but if that fails on CRuby due to being in a trap handler,
+    # run mutex.synchronize(&block) in a separate Thread instead.
+    def self.synchronize(mutex, &block)
+      begin
+        mutex.synchronize(&block)
+      rescue ThreadError => e
+        raise e unless e.message == "can't be called from trap context"
+        # Workaround CRuby issue https://bugs.ruby-lang.org/issues/19473
+        # which raises on Mutex#synchronize in trap handler.
+        # It's expensive to create a Thread just for this,
+        # but better than failing.
+        Thread.new {
+          mutex.synchronize(&block)
+        }.join
       end
     end
   end
-
-  # We keep a private reference so that time mocking libraries won't break
-  # Gem::Timeout.
-  GET_TIME = Process.method(:clock_gettime)
-  private_constant :GET_TIME
+  private_constant :Sync
 
   # :startdoc:
 
-  # Perform an operation in a block, raising an error if it takes longer than
+  # Perform an operation in a block, raising an exception if it takes longer than
   # +sec+ seconds to complete.
   #
   # +sec+:: Number of seconds to wait for the block to terminate. Any non-negative number
@@ -149,45 +212,91 @@ module Gem::Timeout
   #         value of 0 or +nil+ will execute the block without any timeout.
   #         Any negative number will raise an ArgumentError.
   # +klass+:: Exception Class to raise if the block fails to terminate
-  #           in +sec+ seconds.  Omitting will use the default, Gem::Timeout::Error
+  #           in +sec+ seconds.  Omitting will use the default, Gem::Timeout::Error.
   # +message+:: Error message to raise with Exception Class.
-  #             Omitting will use the default, "execution expired"
+  #             Omitting will use the default, <tt>"execution expired"</tt>.
   #
   # Returns the result of the block *if* the block completed before
-  # +sec+ seconds, otherwise throws an exception, based on the value of +klass+.
+  # +sec+ seconds, otherwise raises an exception, based on the value of +klass+.
+  #
+  # The exception raised to terminate the given block is the given +klass+, or
+  # Gem::Timeout::ExitException if +klass+ is not given. The reason for that behavior
+  # is that Gem::Timeout::Error inherits from RuntimeError and might be caught unexpectedly by +rescue+.
+  # Gem::Timeout::ExitException inherits from Exception so it will only be rescued by <tt>rescue Exception</tt>.
+  # Note that the Gem::Timeout::ExitException is translated to a Gem::Timeout::Error once it reaches the Gem::Timeout.timeout call,
+  # so outside that call it will be a Gem::Timeout::Error.
   #
-  # The exception thrown to terminate the given block cannot be rescued inside
-  # the block unless +klass+ is given explicitly. However, the block can use
-  # ensure to prevent the handling of the exception.  For that reason, this
-  # method cannot be relied on to enforce timeouts for untrusted blocks.
+  # In general, be aware that the code block may rescue the exception, and in such a case not respect the timeout.
+  # Also, the block can use +ensure+ to prevent the handling of the exception.
+  # For those reasons, this method cannot be relied on to enforce timeouts for untrusted blocks.
   #
   # If a scheduler is defined, it will be used to handle the timeout by invoking
-  # Scheduler#timeout_after.
+  # Fiber::Scheduler#timeout_after.
   #
   # Note that this is both a method of module Gem::Timeout, so you can <tt>include
   # Gem::Timeout</tt> into your classes so they have a #timeout method, as well as
   # a module method, so you can call it directly as Gem::Timeout.timeout().
-  def timeout(sec, klass = nil, message = nil, &block)   #:yield: +sec+
+  #
+  # ==== Ensuring the exception does not fire inside ensure blocks
+  #
+  # When using Gem::Timeout.timeout, it can be desirable to ensure the timeout exception does not fire inside an +ensure+ block.
+  # The simplest and best way to do so is to put the Gem::Timeout.timeout call inside the body of the +begin+/+ensure+/+end+:
+  #
+  #     begin
+  #       Gem::Timeout.timeout(sec) { some_long_operation }
+  #     ensure
+  #       cleanup # safe, cannot be interrupted by timeout
+  #     end
+  #
+  # If that is not feasible, e.g. if there are +ensure+ blocks inside +some_long_operation+,
+  # they need to not be interrupted by timeout, and it's not possible to move these ensure blocks outside,
+  # one can use Thread.handle_interrupt to delay the timeout exception like so:
+  #
+  #     Thread.handle_interrupt(Gem::Timeout::Error => :never) {
+  #       Gem::Timeout.timeout(sec, Gem::Timeout::Error) do
+  #         setup # timeout cannot happen here, no matter how long it takes
+  #         Thread.handle_interrupt(Gem::Timeout::Error => :immediate) {
+  #           some_long_operation # timeout can happen here
+  #         }
+  #       ensure
+  #         cleanup # timeout cannot happen here, no matter how long it takes
+  #       end
+  #     }
+  #
+  # An important thing to note is the need to pass an exception +klass+ to Gem::Timeout.timeout,
+  # otherwise it does not work. Specifically, using <tt>Thread.handle_interrupt(Gem::Timeout::ExitException => ...)</tt>
+  # is unsupported and causes subtle errors like raising the wrong exception outside the block, do not use that.
+  #
+  # Note that Thread.handle_interrupt is somewhat dangerous because if setup or cleanup hangs
+  # then the current thread will hang too and the timeout will never fire.
+  # Also note the block might run for longer than +sec+ seconds:
+  # e.g. +some_long_operation+ executes for +sec+ seconds + whatever time cleanup takes.
+  #
+  # If you want the timeout to only happen on blocking operations, one can use +:on_blocking+
+  # instead of +:immediate+. However, that means if the block uses no blocking operations after +sec+ seconds,
+  # the block will not be interrupted.
+  def self.timeout(sec, klass = nil, message = nil, &block)   #:yield: +sec+
     return yield(sec) if sec == nil or sec.zero?
     raise ArgumentError, "Timeout sec must be a non-negative number" if 0 > sec
 
     message ||= "execution expired"
 
     if Fiber.respond_to?(:current_scheduler) && (scheduler = Fiber.current_scheduler)&.respond_to?(:timeout_after)
-      return scheduler.timeout_after(sec, klass || Error, message, &block)
-    end
-
-    Gem::Timeout.ensure_timeout_thread_created
-    perform = Proc.new do |exc|
-      request = Request.new(Thread.current, sec, exc, message)
-      QUEUE_MUTEX.synchronize do
-        QUEUE << request
-        CONDVAR.signal
+      perform = Proc.new do |exc|
+        scheduler.timeout_after(sec, exc, message, &block)
       end
-      begin
-        return yield(sec)
-      ensure
-        request.finished
+    else
+      state = State.instance
+      state.ensure_timeout_thread_created
+
+      perform = Proc.new do |exc|
+        request = Request.new(Thread.current, sec, exc, message)
+        state.add_request(request)
+        begin
+          return yield(sec)
+        ensure
+          request.finished
+        end
       end
     end
 
@@ -197,5 +306,9 @@ module Gem::Timeout
       Error.handle_timeout(message, &perform)
     end
   end
-  module_function :timeout
+
+  # See Gem::Timeout.timeout
+  private def timeout(*args, &block)
+    Gem::Timeout.timeout(*args, &block)
+  end
 end

data/lib/rubygems/vendor/uri/lib/uri.rb

@@ -87,6 +87,10 @@
 #  You can redistribute it and/or modify it under the same term as Ruby.
 #
 
+# Skip reloading when an identical copy (e.g. the one shipped inside the Bundler
+# gem) was already required from a different path, to avoid redefinition warnings.
+return if defined?(Gem::URI::VERSION)
+
 module Gem::URI
 end
 

data/{bundler/lib/bundler → lib/rubygems}/vendored_pub_grub.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
-module Bundler; end
 require_relative "vendor/pub_grub/lib/pub_grub"

data/lib/rubygems/version.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+#--
+# Workaround for directly loading Gem::Version in some cases
+module Gem; end
+#++
+
 ##
 # The Version class processes string versions into comparable
 # values. A version string should normally be a series of numbers
@@ -25,133 +30,146 @@
 # 4. 0.9
 #
 # If you want to specify a version restriction that includes both prereleases
-# and regular releases of the 1.x series this is the best way:
+# and regular releases of 1.x or later versions:
 #
-#   s.add_dependency 'example', '>= 1.0.0.a', '< 2.0.0'
+#   s.add_dependency 'example', '>= 1.0.0.a'
 #
 # == How Software Changes
 #
-# Users expect to be able to specify a version constraint that gives them
-# some reasonable expectation that new versions of a library will work with
-# their software if the version constraint is true, and not work with their
-# software if the version constraint is false.  In other words, the perfect
-# system will accept all compatible versions of the library and reject all
-# incompatible versions.
-#
-# Libraries change in 3 ways (well, more than 3, but stay focused here!).
+# Libraries generally change in 3 ways:
 #
-# 1. The change may be an implementation detail only and have no effect on
-#    the client software.
-# 2. The change may add new features, but do so in a way that client software
-#    written to an earlier version is still compatible.
-# 3. The change may change the public interface of the library in such a way
-#    that old software is no longer compatible.
+# 1. The change is an implementation detail, bug fix, security fix, or
+#    optimization, and has no behavioral effect on the software using it.
 #
-# Some examples are appropriate at this point.  Suppose I have a Stack class
-# that supports a <tt>push</tt> and a <tt>pop</tt> method.
+# 2. The change adds new features, and software using those new features is
+#    not compatible with previous versions of the library, but software using
+#    previous versions of the library is compatible with the change.
 #
-# === Examples of Category 1 changes:
+# 3. The change modifies the public interface of some part of the library in
+#    such a way that software that uses that part of the library must be
+#    modified to work.
 #
-# * Switch from an array based implementation to a linked-list based
-#   implementation.
-# * Provide an automatic (and transparent) backing store for large stacks.
-#
-# === Examples of Category 2 changes might be:
-#
-# * Add a <tt>depth</tt> method to return the current depth of the stack.
-# * Add a <tt>top</tt> method that returns the current top of stack (without
-#   changing the stack).
-# * Change <tt>push</tt> so that it returns the item pushed (previously it
-#   had no usable return value).
-#
-# === Examples of Category 3 changes might be:
-#
-# * Changes <tt>pop</tt> so that it no longer returns a value (you must use
-#   <tt>top</tt> to get the top of the stack).
-# * Rename the methods to <tt>push_item</tt> and <tt>pop_item</tt>.
-#
-# == RubyGems Rational Versioning
+# == RubyGems Rational Versioning (the recommended approach)
 #
 # * Versions shall be represented by three non-negative integers, separated
-#   by periods (e.g. 3.1.4).  The first integers is the "major" version
+#   by periods (e.g. 3.1.4).  The first integer is the "major" version
 #   number, the second integer is the "minor" version number, and the third
-#   integer is the "build" number.
+#   integer is the "patch" version number.
 #
-# * A category 1 change (implementation detail) will increment the build
-#   number.
+# * A category 1 change (implementation detail, bug fix, or security fix)
+#   will increment the patch number.
 #
 # * A category 2 change (backwards compatible) will increment the minor
-#   version number and reset the build number.
-#
-# * A category 3 change (incompatible) will increment the major build number
-#   and reset the minor and build numbers.
-#
-# * Any "public" release of a gem should have a different version.  Normally
-#   that means incrementing the build number.  This means a developer can
-#   generate builds all day long, but as soon as they make a public release,
-#   the version must be updated.
-#
-# === Examples
+#   version number and reset the patch number.
 #
-# Let's work through a project lifecycle using our Stack example from above.
+# * A category 3 change (incompatible) will increment the major version number
+#   and reset the minor and patch numbers.
 #
-# Version 0.0.1:: The initial Stack class is release.
-# Version 0.0.2:: Switched to a linked=list implementation because it is
-#                 cooler.
-# Version 0.1.0:: Added a <tt>depth</tt> method.
-# Version 1.0.0:: Added <tt>top</tt> and made <tt>pop</tt> return nil
-#                 (<tt>pop</tt> used to return the  old top item).
-# Version 1.1.0:: <tt>push</tt> now returns the value pushed (it used it
-#                 return nil).
-# Version 1.1.1:: Fixed a bug in the linked list implementation.
-# Version 1.1.2:: Fixed a bug introduced in the last fix.
+# * Any "public" release of a gem should have a different version.
 #
-# Client A needs a stack with basic push/pop capability.  They write to the
-# original interface (no <tt>top</tt>), so their version constraint looks like:
+# == Optimistic Vs. Pessimistic Dependency Versioning
 #
-#   gem 'stack', '>= 0.0'
-#
-# Essentially, any version is OK with Client A.  An incompatible change to
-# the library will cause them grief, but they are willing to take the chance
-# (we call Client A optimistic).
-#
-# Client B is just like Client A except for two things: (1) They use the
-# <tt>depth</tt> method and (2) they are worried about future
-# incompatibilities, so they write their version constraint like this:
-#
-#   gem 'stack', '~> 0.1'
-#
-# The <tt>depth</tt> method was introduced in version 0.1.0, so that version
-# or anything later is fine, as long as the version stays below version 1.0
-# where incompatibilities are introduced.  We call Client B pessimistic
-# because they are worried about incompatible future changes (it is OK to be
-# pessimistic!).
-#
-# == Preventing Version Catastrophe:
-#
-# From: https://www.zenspider.com/ruby/2008/10/rubygems-how-to-preventing-catastrophe.html
-#
-# Let's say you're depending on the fnord gem version 2.y.z. If you
-# specify your dependency as ">= 2.0.0" then, you're good, right? What
-# happens if fnord 3.0 comes out and it isn't backwards compatible
-# with 2.y.z? Your stuff will break as a result of using ">=". The
-# better route is to specify your dependency with an "approximate" version
-# specifier ("~>"). They're a tad confusing, so here is how the dependency
-# specifiers work:
-#
-#   Specification From  ... To (exclusive)
-#   ">= 3.0"      3.0   ... &infin;
-#   "~> 3.0"      3.0   ... 4.0
-#   "~> 3.0.0"    3.0.0 ... 3.1
-#   "~> 3.5"      3.5   ... 4.0
-#   "~> 3.5.0"    3.5.0 ... 3.6
-#   "~> 3"        3.0   ... 4.0
-#
-# For the last example, single-digit versions are automatically extended with
-# a zero to give a sensible result.
-
-# Workaround for directly loading Gem::Version in some cases
-module Gem; end
+# Users expect to be able to specify a version constraint that gives them
+# a reasonable expectation that new versions of a library will work with
+# their software if the version constraint is true, and not work with their
+# software if the version constraint is false.  In other words, the perfect
+# system will accept all compatible versions of the library and reject all
+# incompatible versions. Unfortunately, there is no perfect system, as you
+# cannot predict the future. You can never know whether a future version of
+# a library will contain which type of change.
+#
+# There are two common outlooks on dependency versioning:
+#
+# 1. Optimistic. This does not set an upper bound on a dependency. It is
+#    possible that a future version of a dependency will break the software,
+#    and in that case, the dependency version will need to be updated and
+#    changes will need to be made.
+#
+# 2. Pessimistic. This assumes all major version changes of a dependency will
+#    break the software, and that patch or minor changes of a dependency will
+#    not break the software. If there is a major version of a dependency
+#    released, the dependency version must be updated in order to use it, even
+#    if no code changes are actually needed.
+#
+# In general, optimistic versioning is superior to pessimistic versioning.
+# Pessimistic versioning is often wrong in both directions. Dependencies can
+# release patch or minor versions that contain incompatibilities. One
+# common reason is that a security fix may require a backwards-incompatible API
+# change. In this case, even though pessimistic versioning was used, it
+# didn't even save effort, as you still need to make code changes and adjust
+# dependency versions. Similarly, for all but the smallest dependencies, just
+# because the dependency made a backwards incompatible change to one interface
+# doesn't mean the dependency made a backwards incompatible change to an
+# interface that the software is using. It is a common problem that a
+# dependency will release a new major version and the software does not require
+# any changes in order to use it. In this case, being pessimistic results in
+# additional work for no benefit.
+#
+# When a library uses pessimistic versioning of dependencies, it causes
+# significant problems if that library is not diligent about updating
+# dependency versions and any library is depending on that library.
+# For example:
+#
+# * Library A is currently on release 1.2.3.
+#
+# * Library B is at version 2.3.4 and has a pessimistic dependency on
+#   library A, using ~> 1.0 (>= 1.0, < 2).
+#
+# * Library C is at version 3.4.5 and has an optimistic dependency on
+#   library A, using >= 1.0.
+#
+# * Library D has optimistic dependencies on both libraries B and C.
+#
+# * Library A releases a new major version, 2.0.0, with new features, which
+#   is mostly backwards compatible, but does contain some backwards
+#   incompatible changes.
+#
+# * Library B would work with A 2.0.0, but cannot use it due to pessimistic
+#   versioning.
+#
+# * Library C wants to use the new features in the major release of library
+#   A to implement its own new features, so it does so, bumps the
+#   dependency version of A to >= 2.0, and releases version 3.5.0.
+#
+# * Library D cannot upgrade to the new version of library C, because it
+#   depends on library B, which has a pessimistic dependency on library A.
+#
+# * Library C releases a security fix patch version 3.5.1 to fix a
+#   vulnerability present in all previous versions.
+#
+# * Library D is now in a terrible situation. It cannot upgrade to library
+#   C 3.5.1, as that requires library A > 2.0, because it depends on library
+#   B, which requires library A > 1.0, < 2, even though library B would work
+#   fine with library A 2.0.0.
+#
+# This type of situation brought on by pessimistic versioning is unfortunately
+# both common and serious in practice.
+#
+# This is not to say that optimistic versioning never causes a problem.
+# However, with optimistic versioning, if there is a problem, it can be solved
+# with the addition of a single dependency. For example, continuing the
+# previous example:
+#
+# * Library A releases a new major version, 3.0.0, which makes backwards
+#   incompatible changes that break library C.
+#
+# * Until library C releases an updated version with new changes, library
+#   D only needs to set a specific dependency on library A for > 2.0, < 3,
+#   until library C is updated to work with the new version of library A.
+#
+# Both optimistic versioning and pessimistic versioning have problems in
+# certain cases. However, it's significantly easier to fix optimistic
+# versioning problems than to fix pessimistic versioning problems.
+#
+# That is not to say that pessimistic versioning is never appropriate. If the
+# dependency is a library that adds a single method, where any change resulting
+# in a major version bump would probably break a library using it, then using
+# pessimistic versioning may be warranted. Additionally, if a dependency has
+# already announced or committed backwards incompatible changes that would
+# break a library's use of it, then having that library use a pessimistic
+# version constraint would likely be warranted. However, outside of
+# specific situations, you should avoid using pessimistic versioning, as the
+# costs typically exceed the benefits.
 
 class Gem::Version
   include Comparable
@@ -325,7 +343,7 @@ class Gem::Version
   end
 
   ##
-  # A recommended version for use with a ~> Requirement.
+  # A recommended version for use with a >= Requirement.
 
   def approximate_recommendation
     segments = self.segments
@@ -334,7 +352,7 @@ class Gem::Version
     segments.pop    while segments.size > 2
     segments.push 0 while segments.size < 2
 
-    recommendation = "~> #{segments.join(".")}"
+    recommendation = ">= #{segments.join(".")}"
     recommendation += ".a" if prerelease?
     recommendation
   end