rubygems-update 3.5.3 → 3.7.1

data/bundler/lib/bundler.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "bundler/rubygems_ext"
 require_relative "bundler/vendored_fileutils"
 require "pathname"
 require "rbconfig"
@@ -7,10 +8,8 @@ require "rbconfig"
 require_relative "bundler/errors"
 require_relative "bundler/environment_preserver"
 require_relative "bundler/plugin"
-require_relative "bundler/rubygems_ext"
 require_relative "bundler/rubygems_integration"
 require_relative "bundler/version"
-require_relative "bundler/constants"
 require_relative "bundler/current_ruby"
 require_relative "bundler/build_metadata"
 
@@ -40,7 +39,9 @@ module Bundler
   SUDO_MUTEX = Thread::Mutex.new
 
   autoload :Checksum,               File.expand_path("bundler/checksum", __dir__)
+  autoload :CLI,                    File.expand_path("bundler/cli", __dir__)
   autoload :CIDetector,             File.expand_path("bundler/ci_detector", __dir__)
+  autoload :CompactIndexClient,     File.expand_path("bundler/compact_index_client", __dir__)
   autoload :Definition,             File.expand_path("bundler/definition", __dir__)
   autoload :Dependency,             File.expand_path("bundler/dependency", __dir__)
   autoload :Deprecate,              File.expand_path("bundler/deprecate", __dir__)
@@ -50,8 +51,8 @@ module Bundler
   autoload :Env,                    File.expand_path("bundler/env", __dir__)
   autoload :Fetcher,                File.expand_path("bundler/fetcher", __dir__)
   autoload :FeatureFlag,            File.expand_path("bundler/feature_flag", __dir__)
+  autoload :FREEBSD,                File.expand_path("bundler/constants", __dir__)
   autoload :GemHelper,              File.expand_path("bundler/gem_helper", __dir__)
-  autoload :GemHelpers,             File.expand_path("bundler/gem_helpers", __dir__)
   autoload :GemVersionPromoter,     File.expand_path("bundler/gem_version_promoter", __dir__)
   autoload :Graph,                  File.expand_path("bundler/graph", __dir__)
   autoload :Index,                  File.expand_path("bundler/index", __dir__)
@@ -60,6 +61,8 @@ module Bundler
   autoload :LazySpecification,      File.expand_path("bundler/lazy_specification", __dir__)
   autoload :LockfileParser,         File.expand_path("bundler/lockfile_parser", __dir__)
   autoload :MatchRemoteMetadata,    File.expand_path("bundler/match_remote_metadata", __dir__)
+  autoload :Materialization,        File.expand_path("bundler/materialization", __dir__)
+  autoload :NULL,                   File.expand_path("bundler/constants", __dir__)
   autoload :ProcessLock,            File.expand_path("bundler/process_lock", __dir__)
   autoload :RemoteSpecification,    File.expand_path("bundler/remote_specification", __dir__)
   autoload :Resolver,               File.expand_path("bundler/resolver", __dir__)
@@ -78,6 +81,7 @@ module Bundler
   autoload :UI,                     File.expand_path("bundler/ui", __dir__)
   autoload :URICredentialsFilter,   File.expand_path("bundler/uri_credentials_filter", __dir__)
   autoload :URINormalizer,          File.expand_path("bundler/uri_normalizer", __dir__)
+  autoload :WINDOWS,                File.expand_path("bundler/constants", __dir__)
   autoload :SafeMarshal,            File.expand_path("bundler/safe_marshal", __dir__)
 
   class << self
@@ -109,13 +113,13 @@ module Bundler
     end
 
     def configured_bundle_path
-      @configured_bundle_path ||= settings.path.tap(&:validate!)
+      @configured_bundle_path ||= Bundler.settings.path.tap(&:validate!)
     end
 
     # Returns absolute location of where binstubs are installed to.
     def bin_path
       @bin_path ||= begin
-        path = settings[:bin] || "bin"
+        path = Bundler.settings[:bin] || "bin"
         path = Pathname.new(path).expand_path(root).expand_path
         mkdir_p(path)
         path
@@ -165,6 +169,29 @@ module Bundler
       end
     end
 
+    def auto_switch
+      self_manager.restart_with_locked_bundler_if_needed
+    end
+
+    # Automatically install dependencies if settings[:auto_install] exists.
+    # This is set through config cmd `bundle config set --global auto_install 1`.
+    #
+    # Note that this method `nil`s out the global Definition object, so it
+    # should be called first, before you instantiate anything like an
+    # `Installer` that'll keep a reference to the old one instead.
+    def auto_install
+      return unless Bundler.settings[:auto_install]
+
+      begin
+        definition.specs
+      rescue GemNotFound, GitError
+        ui.info "Automatically installing missing gems."
+        reset!
+        CLI::Install.new({}).run
+        reset!
+      end
+    end
+
     # Setups Bundler environment (see Bundler.setup) if it is not already set,
     # and loads all gems from groups specified. Unlike ::setup, can be called
     # multiple times with different groups (if they were allowed by setup).
@@ -200,20 +227,21 @@ module Bundler
     #
     # @param unlock [Hash, Boolean, nil] Gems that have been requested
     #   to be updated or true if all gems should be updated
+    # @param lockfile [Pathname] Path to Gemfile.lock
     # @return [Bundler::Definition]
-    def definition(unlock = nil)
+    def definition(unlock = nil, lockfile = default_lockfile)
       @definition = nil if unlock
       @definition ||= begin
         configure
-        Definition.build(default_gemfile, default_lockfile, unlock)
+        Definition.build(default_gemfile, lockfile, unlock)
       end
     end
 
     def frozen_bundle?
-      frozen = settings[:frozen]
+      frozen = Bundler.settings[:frozen]
       return frozen unless frozen.nil?
 
-      settings[:deployment]
+      Bundler.settings[:deployment]
     end
 
     def locked_gems
@@ -226,12 +254,6 @@ module Bundler
         end
     end
 
-    def most_specific_locked_platform?(platform)
-      return false unless defined?(@definition) && @definition
-
-      definition.most_specific_locked_platform == platform
-    end
-
     def ruby_scope
       "#{Bundler.rubygems.ruby_engine}/#{RbConfig::CONFIG["ruby_version"]}"
     end
@@ -320,7 +342,7 @@ module Bundler
 
     def app_cache(custom_path = nil)
       path = custom_path || root
-      Pathname.new(path).join(settings.app_cache_path)
+      Pathname.new(path).join(Bundler.settings.app_cache_path)
     end
 
     def tmp(name = Process.pid.to_s)
@@ -335,7 +357,7 @@ module Bundler
     def settings
       @settings ||= Settings.new(app_config_path)
     rescue GemfileNotFound
-      @settings = Settings.new(Pathname.new(".bundle").expand_path)
+      @settings = Settings.new
     end
 
     # @return [Hash] Environment present before Bundler was activated
@@ -357,28 +379,12 @@ module Bundler
 
     # @return [Hash] Environment with all bundler-related variables removed
     def unbundled_env
-      env = original_env
-
-      if env.key?("BUNDLER_ORIG_MANPATH")
-        env["MANPATH"] = env["BUNDLER_ORIG_MANPATH"]
-      end
-
-      env.delete_if {|k, _| k[0, 7] == "BUNDLE_" }
-
-      if env.key?("RUBYOPT")
-        rubyopt = env["RUBYOPT"].split(" ")
-        rubyopt.delete("-r#{File.expand_path("bundler/setup", __dir__)}")
-        rubyopt.delete("-rbundler/setup")
-        env["RUBYOPT"] = rubyopt.join(" ")
-      end
-
-      if env.key?("RUBYLIB")
-        rubylib = env["RUBYLIB"].split(File::PATH_SEPARATOR)
-        rubylib.delete(__dir__)
-        env["RUBYLIB"] = rubylib.join(File::PATH_SEPARATOR)
-      end
+      unbundle_env(original_env)
+    end
 
-      env
+    # Remove all bundler-related variables from ENV
+    def unbundle_env!
+      ENV.replace(unbundle_env(ENV))
     end
 
     # Run block with environment present before Bundler was activated
@@ -448,10 +454,14 @@ module Bundler
     end
 
     def local_platform
-      return Gem::Platform::RUBY if settings[:force_ruby_platform]
+      return Gem::Platform::RUBY if Bundler.settings[:force_ruby_platform]
       Gem::Platform.local
     end
 
+    def generic_local_platform
+      Gem::Platform.generic(local_platform)
+    end
+
     def default_gemfile
       SharedHelpers.default_gemfile
     end
@@ -482,24 +492,33 @@ module Bundler
     end
 
     def mkdir_p(path)
-      SharedHelpers.filesystem_access(path, :write) do |p|
+      SharedHelpers.filesystem_access(path, :create) do |p|
         FileUtils.mkdir_p(p)
       end
     end
 
     def which(executable)
-      if File.file?(executable) && File.executable?(executable)
-        executable
-      elsif paths = ENV["PATH"]
+      executable_path = find_executable(executable)
+      return executable_path if executable_path
+
+      if (paths = ENV["PATH"])
         quote = '"'
         paths.split(File::PATH_SEPARATOR).find do |path|
           path = path[1..-2] if path.start_with?(quote) && path.end_with?(quote)
-          executable_path = File.expand_path(executable, path)
-          return executable_path if File.file?(executable_path) && File.executable?(executable_path)
+          executable_path = find_executable(File.expand_path(executable, path))
+          return executable_path if executable_path
         end
       end
     end
 
+    def find_executable(path)
+      extensions = RbConfig::CONFIG["EXECUTABLE_EXTS"]&.split
+      extensions = [RbConfig::CONFIG["EXEEXT"]] unless extensions&.any?
+      candidates = extensions.map {|ext| "#{path}#{ext}" }
+
+      candidates.find {|candidate| File.file?(candidate) && File.executable?(candidate) }
+    end
+
     def read_file(file)
       SharedHelpers.filesystem_access(file, :read) do
         File.open(file, "r:UTF-8", &:read)
@@ -531,15 +550,7 @@ module Bundler
     def load_gemspec_uncached(file, validate = false)
       path = Pathname.new(file)
       contents = read_file(file)
-      spec = if contents.start_with?("---") # YAML header
-        eval_yaml_gemspec(path, contents)
-      else
-        # Eval the gemspec from its parent directory, because some gemspecs
-        # depend on "./" relative paths.
-        SharedHelpers.chdir(path.dirname.to_s) do
-          eval_gemspec(path, contents)
-        end
-      end
+      spec = eval_gemspec(path, contents)
       return unless spec
       spec.loaded_from = path.expand_path.to_s
       Bundler.rubygems.validate(spec) if validate
@@ -552,11 +563,11 @@ module Bundler
 
     def git_present?
       return @git_present if defined?(@git_present)
-      @git_present = Bundler.which("git#{RbConfig::CONFIG["EXEEXT"]}")
+      @git_present = Bundler.which("git")
     end
 
     def feature_flag
-      @feature_flag ||= FeatureFlag.new(VERSION)
+      @feature_flag ||= FeatureFlag.new(Bundler.settings[:simulate_version] || VERSION)
     end
 
     def reset!
@@ -572,7 +583,6 @@ module Bundler
 
     def reset_paths!
       @bin_path = nil
-      @bundler_major_version = nil
       @bundle_path = nil
       @configure = nil
       @configured_bundle_path = nil
@@ -607,6 +617,30 @@ module Bundler
 
     private
 
+    def unbundle_env(env)
+      if env.key?("BUNDLER_ORIG_MANPATH")
+        env["MANPATH"] = env["BUNDLER_ORIG_MANPATH"]
+      end
+
+      env.delete_if {|k, _| k[0, 7] == "BUNDLE_" }
+      env.delete("BUNDLER_SETUP")
+
+      if env.key?("RUBYOPT")
+        rubyopt = env["RUBYOPT"].split(" ")
+        rubyopt.delete("-r#{File.expand_path("bundler/setup", __dir__)}")
+        rubyopt.delete("-rbundler/setup")
+        env["RUBYOPT"] = rubyopt.join(" ")
+      end
+
+      if env.key?("RUBYLIB")
+        rubylib = env["RUBYLIB"].split(File::PATH_SEPARATOR)
+        rubylib.delete(__dir__)
+        env["RUBYLIB"] = rubylib.join(File::PATH_SEPARATOR)
+      end
+
+      env
+    end
+
     def load_marshal(data, marshal_proc: nil)
       Marshal.load(data, marshal_proc)
     rescue TypeError => e
@@ -617,16 +651,22 @@ module Bundler
       Kernel.require "psych"
 
       Gem::Specification.from_yaml(contents)
-    rescue ::Psych::SyntaxError, ArgumentError, Gem::EndOfYAMLException, Gem::Exception
-      eval_gemspec(path, contents)
     end
 
     def eval_gemspec(path, contents)
-      eval(contents, TOPLEVEL_BINDING.dup, path.expand_path.to_s)
+      if contents.start_with?("---") # YAML header
+        eval_yaml_gemspec(path, contents)
+      else
+        # Eval the gemspec from its parent directory, because some gemspecs
+        # depend on "./" relative paths.
+        SharedHelpers.chdir(path.dirname.to_s) do
+          eval(contents, TOPLEVEL_BINDING.dup, path.expand_path.to_s)
+        end
+      end
     rescue ScriptError, StandardError => e
       msg = "There was an error while loading `#{path.basename}`: #{e.message}"
 
-      raise GemspecError, Dsl::DSLError.new(msg, path, e.backtrace, contents)
+      raise GemspecError, Dsl::DSLError.new(msg, path.to_s, e.backtrace, contents)
     end
 
     def configure_gem_path

data/{bundler → doc/bundler}/UPGRADING.md

@@ -1,150 +1,86 @@
 # Upgrading
 
-## Bundler 3
+## Bundler 4
+
+In order to prepare for Bundler 4, you can easily configure Bundler 2.7 to
+behave exactly like Bundler 4 will behave. To do so, set the environment
+variable `BUNDLE_SIMULATE_VERSION` to `4`. Alternatively, you can use `bundle
+config` and enable "Bundler 4 mode" either globally through `bundle config set
+--global simulate_version 4`, or locally through `bundle config set --local
+simulate_version 4`. From now on in this document we will assume that all three
+of these configuration options are available, but will only mention `bundle
+config set <option> <value>`.
 
 The following is a summary of the changes that we plan to introduce in Bundler
-3, why we will be making those changes, and what the deprecation process will
-look like. All these deprecations are printed by default in the Bundler 2.1 release.
-
-If you don't want to deal with deprecations right now and want to toggle them
-off, you can do it through configuration. Set the `BUNDLE_SILENCE_DEPRECATIONS`
-environment variable to "true", or configure it through `bundle config` either
-globally through `bundle config set --global silence_deprecations true` command, or
-locally through `bundle config set --local silence_deprecations true`. From now
-on in this document we will assume that all three of these configuration options
-are available, but will only mention `bundle config set <option> <value>`.
-
-As a general note, these changes are intended to improve the experience using
-bundler for _new_ users, who have no existing usage routines nor possibly biased
-opinions about how the tool should work based on how it has historically worked.
-We do understand that changing behaviour that have been existing for years can
-be annoying for old users, that's why we intend to make this process as smooth
-as possible for everyone.
-
-I'll be dividing the deprecations into four groups: CLI deprecations, Helper
-deprecations, DSL deprecations, and misc deprecations. Let's dive into each of
-them.
-
-### CLI deprecations
-
-The CLI defines a set of commands and options that can be used by our users to
-create command lines that bundler can understand. There's a number of changes
-in the upcoming 3 version.
-
-* Flags passed to `bundle install` that relied on being remembered across invocations have been deprecated.
-
-  In particular, the `--clean`, `--deployment`, `--frozen`,
-  `--no-prune`, `--path`, `--shebang`, `--system`, `--without`, and `--with`
-  options to `bundle install`.
-
-  Remembering CLI options has been a source of historical confusion and bug
-  reports, not only for beginners but also for experienced users. A CLI tool
-  should not behave differently across exactly the same invocations _unless_
-  explicitly configured to do so. This is what configuration is about after all,
-  and things should never be silently configured without the user knowing about
-  it.
-
-  The problem with changing this behavior is that very common workflows are
-  relying on it. For example, when you run `bundle install --without
-  development:test` in production, those flags are persisted in the app's
-  configuration file and further `bundle` invocations will happily ignore
-  development and test gems.  This magic will disappear from bundler 3, and
-  you will explicitly need to configure it, either through environment
-  variables, application configuration, or machine configuration. For example,
-  with `bundle config set --local without development test`.
-
-  The removal of this kind of flag also applies to analogous commands, for
-  example, to `bundle check --path`.
-
-* The `--force` flag to `bundle install` and `bundle update` has been renamed to `--redownload`.
-
-  This is just a simple rename of the flag, to make more apparent what it
-  actually does. This flag forces redownloading every gem, it doesn't "force"
-  anything else.
+4, and why we will be making those changes. Some of them should be well known
+already by existing users, because we have been printing deprecation messages
+for years, but some of them are defaults that will be switched in Bundler 4 and
+needs some heads up.
 
-* `bundle viz` will be removed and extracted to a plugin.
+### Running just `bundle`  will print help usage
 
-  This is the only bundler command requiring external dependencies, both an OS
-  dependency (the `graphviz` package) and a gem dependency (the `ruby-graphviz`
-  gem). Removing these dependencies will make development easier and it was also
-  seen by the bundler team as an opportunity to develop a bundler plugin that
-  it's officially maintained by the bundler team, and that users can take as a
-  reference to develop their own plugins. The plugin will contain the same code
-  as the old core command, the only difference being that the command is now
-  implemented as `bundle graph` which is much easier to understand. However, the
-  details of the plugin are under discussion. See [#3333](https://github.com/rubygems/rubygems/issues/3333).
+We're changing this default to make Bundler more friendly for new users. We do
+understand that long time users already know how Bundler works and find useful
+that just `bundle` defaults to `bundle install`. Those users can keep the
+existing default by configuring
 
-* The `bundle console` will be removed and replaced with `bin/console`.
+```
+bundle config default_cli_command install
+```
 
-  Over time we found `bundle console` hard to maintain because every user would
-  want to add her own specific tweaks to it. In order to ease maintenance and
-  reduce bikeshedding discussions, we're removing the `bundle console` command
-  in favor of a `bin/console` script created by `bundle gem` on gem generation
-  that users can tweak to their needs.
+### Bundler will install to a `.bundle` folder relative to the Gemfile location by default
 
+We're making this change to improve isolation. It will install gems to a
+`.bundle` folder relative to the Gemfile location, instead of a global system folder.
 
-* The `bundle install` command will no longer accept a `--binstubs` flag.
+The previous default of installing to system changes can be kept with `bundle
+config path.system true`.
 
-  The `--binstubs` option has been removed from `bundle install` and replaced
-  with the `bundle binstubs` command. The `--binstubs` flag would create
-  binstubs for all executables present inside the gems in the project. This was
-  hardly useful since most users will only use a subset of all the binstubs
-  available to them. Also, it would force the introduction of a bunch of most
-  likely unused files into source control. Because of this, binstubs now must
-  be created and checked into version control individually.
+Related to this change, and to alleviate potential bad consequences from it,
+we're also shipping some related changes:
 
+* To keep disk usage under control, Bundler will cleanup unused gems when
+  installing gems per application using the new default. This new behavior can
+  be disabled by toggling back installing to system gems as explained before, or
+  by configuring `bundle config clean false`.
 
-* The `bundle inject` command is deprecated and replaced with `bundle add`.
+* To avoid duplicate downloads of `.gem` packages and recompilation of
+  extensions, Bundler will keep a global cache of gem packages and compiled
+  extensions. This new behaviour can be disabled with `bundle config
+  global_gem_cache false`, or by toggling back installing to system gems as
+  explained before.
 
-  We believe the new command fits the user's mental model better and it supports
-  a wider set of use cases. The interface supported by `bundle inject` works
-  exactly the same in `bundle add`, so it should be easy to migrate to the new
-  command.
+### Flags passed to `bundle install` that relied on being remembered across invocations will be removed
 
-#### Cancelled CLI deprecations
+In particular, the `--clean`, `--deployment`, `--frozen`, `--no-prune`,
+`--path`, `--shebang`, `--system`, `--without`, and `--with` options to `bundle
+install`.
 
-These deprecations have been initially announced before, but the deprecations
-were cancelled before the release of Bundler 2.1.0 in [rubygems/bundler#7475](https://github.com/rubygems/bundler/pull/7475).
+Remembering CLI options has been a source of historical confusion and bug
+reports, not only for beginners but also for experienced users. A CLI tool
+should not behave differently across exactly the same invocations _unless_
+explicitly configured to do so. This is what configuration is about after all,
+and things should never be silently configured without the user knowing about
+it.
 
-* ~The `bundle update` command will no longer update all gems, you'll need to pass `--all` to it.~ (postponed)
+The problem with changing this behavior is that very common workflows are
+relying on it. For example, when you run `bundle install --without
+development:test` in production, those flags are persisted in the app's
+configuration file and further `bundle` invocations will happily ignore
+development and test gems.  This magic will disappear from bundler 4, and you
+will explicitly need to configure it, either through environment variables,
+application configuration, or machine configuration. For example, with `bundle
+config set --local without development test`.
 
-* ~The `bundle config` command will no longer accept old subcommand-based interface before Bundler 2.1.~ (postponed)
+### Bundler will include checksums in the lockfile by default
 
-### Helper deprecations
+We shipped this security feature recently and we believe it's time to turn it on
+by default, so that everyone benefits from the extra security assurances by default.
 
-* `Bundler.clean_env`, `Bundler.with_clean_env`, `Bundler.clean_system`, and `Bundler.clean_exec` are deprecated.
+### Strict source pinning in Gemfile is enforced by default
 
-  All of these helpers ultimately use `Bundler.clean_env` under the hood, which
-  makes sure all bundler-related environment are removed inside the block it
-  yields.
-
-  After quite a lot user reports, we noticed that users don't usually want this
-  but instead want the bundler environment as it was before the current process
-  was started. Thus, `Bundler.with_original_env`, `Bundler.original_system`, and
-  `Bundler.original_exec` were born. They all use the new `Bundler.original_env`
-  under the hood.
-
-  There's however some specific cases where the good old `Bundler.clean_env`
-  behavior can be useful. For example, when testing Rails generators, you really
-  want an environment where `bundler` is out of the picture. This is why we
-  decided to keep the old behavior under a new more clear name, because we
-  figured the word "clean" was too ambiguous. So we have introduced
-  `Bundler.unbundled_env`, `Bundler.with_unbundled_env`,
-  `Bundler.unbundled_system`, and `Bundler.unbundled_exec`.
-
-* `Bundler.environment` is deprecated in favor of `Bundler.load`.
-
-  We're not sure how people might be using this directly but we have removed the
-  `Bundler::Environment` class which was instantiated by `Bundler.environment`
-  since we realized the `Bundler::Runtime` class was the same thing. During the
-  transition `Bundler.environment` will delegate to `Bundler.load`, which holds
-  the reference to the `Bundler::Environment`.
-
-#### DSL deprecations
-
-The following deprecations in bundler's DSL are meant to prepare for the strict
-source pinning in bundler 3, where the source for every dependency will be
-unambiguously defined.
+In bundler 4, the source for every dependency will be unambiguously defined, and
+Bundler will refuse to run otherwise.
 
 * Multiple global Gemfile sources will no longer be supported.
 
@@ -207,7 +143,76 @@ unambiguously defined.
   end
   ```
 
-#### Misc deprecations
+#### Notable CLI changes
+
+* `bundle viz` will be removed and extracted to a plugin.
+
+  This is the only bundler command requiring external dependencies, both an OS
+  dependency (the `graphviz` package) and a gem dependency (the `ruby-graphviz`
+  gem). Removing these dependencies will make development easier and it was also
+  seen by the bundler team as an opportunity to develop a bundler plugin that
+  it's officially maintained by the bundler team, and that users can take as a
+  reference to develop their own plugins. The plugin will contain the same code
+  as the old core command, the only difference being that the command is now
+  implemented as `bundle graph` which is much easier to understand. However, the
+  details of the plugin are under discussion. See [#3333](https://github.com/rubygems/rubygems/issues/3333).
+
+* The `bundle install` command will no longer accept a `--binstubs` flag.
+
+  The `--binstubs` option has been removed from `bundle install` and replaced
+  with the `bundle binstubs` command. The `--binstubs` flag would create
+  binstubs for all executables present inside the gems in the project. This was
+  hardly useful since most users will only use a subset of all the binstubs
+  available to them. Also, it would force the introduction of a bunch of most
+  likely unused files into source control. Because of this, binstubs now must
+  be created and checked into version control individually.
+
+* The `bundle inject` command will be replaced with `bundle add`
+
+  We believe the new command fits the user's mental model better and it supports
+  a wider set of use cases. The interface supported by `bundle inject` works
+  exactly the same in `bundle add`, so it should be easy to migrate to the new
+  command.
+
+### Other notable changes
+
+* Git and Path gems will be included in `vendor/cache` by default
+
+  We're unsure why these gems were treated specially so we'll start caching them
+  normally.
+
+* Bundler will use cached local data if available when network issues are found
+  during resolution.
+
+  Just trying to provide a more resilient behavior here.
+
+* `Bundler.clean_env`, `Bundler.with_clean_env`, `Bundler.clean_system`, and `Bundler.clean_exec` will be removed
+
+  All of these helpers ultimately use `Bundler.clean_env` under the hood, which
+  makes sure all bundler-related environment are removed inside the block it
+  yields.
+
+  After quite a lot user reports, we noticed that users don't usually want this
+  but instead want the bundler environment as it was before the current process
+  was started. Thus, `Bundler.with_original_env`, `Bundler.original_system`, and
+  `Bundler.original_exec` were born. They all use the new `Bundler.original_env`
+  under the hood.
+
+  There's however some specific cases where the good old `Bundler.clean_env`
+  behavior can be useful. For example, when testing Rails generators, you really
+  want an environment where `bundler` is out of the picture. This is why we
+  decided to keep the old behavior under a new more clear name, because we
+  figured the word "clean" was too ambiguous. So we have introduced
+  `Bundler.unbundled_env`, `Bundler.with_unbundled_env`,
+  `Bundler.unbundled_system`, and `Bundler.unbundled_exec`.
+
+* `Bundler.environment` is deprecated in favor of `Bundler.load`.
+
+  We're not sure how people might be using this directly but we have removed the
+  `Bundler::Environment` class which was instantiated by `Bundler.environment`
+  since we realized the `Bundler::Runtime` class was the same thing. During the
+  transition `Bundler.environment` will delegate to `Bundler.load`, which holds
+  the reference to the `Bundler::Environment`.
 
 * Deployment helpers for `vlad` and `capistrano` are being removed.