Merge #7295

7295: Changelog for first 2.1.0 pre-release  r=deivid-rodriguez a=deivid-rodriguez

### What was the end-user problem that led to this PR?

The problem was that I want to release a first pre-release of bundler 2.1.0, but I don't have a changelog for it.

### What was your diagnosis of the problem?

My diagnosis was that I needed to compile a changelog.

### What is your fix for the problem, implemented in this PR?

My fix is write the changelog.

### Why did you choose this fix out of the possible options?

I chose this fix because we used to have some automated change log handling, but I'm not sure how it work, so I instead just through each PR including user facing changes manually, with the aid of some helper tasks we have in our Rakefile.

This is still a WIP, because I might include some more PRs, and I also want to elaborate a bit on the deprecations that will get enabled, but it should be ready for an initial review.

Co-authored-by: David Rodríguez <deivid.rodriguez@riseup.net>

2 files changed, 330 insertions, 3 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2392844047..3f2a6f742c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,101 @@
+## 2.1.0.pre.1
+
+One of the biggest changes in bundler 2.1.0 is that deprecations for upcoming
+breaking changes in bundler 3 will be turned on by default. We do this to grab
+feedback and comunicate early to our users the kind of changes we're intending
+to ship with bundler 3. See
+[#6965](https://github.com/bundler/bundler/pull/6965).
+
+Another important improvement is a better coexistence between bundler
+installations and the default copy of bundler that comes with ruby installed as
+a default gem. Since bundler is shipped as a default gem with ruby, a number of
+users have been affected by issues where bundler ends up failing due to version
+mismatches, because at some point of the execution, bundler switches to run the
+default copy instead of the expected version. A number of PRs have been focused
+on minimizing (hopefully eliminating) this, such as
+[#7100](https://github.com/bundler/bundler/pull/7100),
+[#7137](https://github.com/bundler/bundler/pull/7137),
+[#6996](https://github.com/bundler/bundler/pull/6996),
+[#7056](https://github.com/bundler/bundler/pull/7056),
+[#7062](https://github.com/bundler/bundler/pull/7062),
+[#7193](https://github.com/bundler/bundler/pull/7193),
+[#7216](https://github.com/bundler/bundler/pull/7216),
+[#7274](https://github.com/bundler/bundler/pull/7274)
+
+Deprecations:
+
+  * See the [the upgrading document](UPGRADING.md) for a detailed explanation of
+    the deprecations that are getting enabled in bundler 2.1, and the future
+    breaking changes in bundler 3.
+
+Features:
+
+  - Reimplement `config` command using subcommands ([#5981](https://github.com/bundler/bundler/pull/5981))
+  - Add `bundle plugin list` command ([#6120](https://github.com/bundler/bundler/pull/6120))
+  - Introduce a `bundle lock --gemfile` flag ([#6748](https://github.com/bundler/bundler/pull/6748))
+  - Add local git repository source option (`--local_git`) to plugin installation ([#6749](https://github.com/bundler/bundler/pull/6749))
+  - Add `quiet` flag to inline bundler ([#6828](https://github.com/bundler/bundler/pull/6828))
+  - Introduce a `prefer_patch` configuration that makes `bundle update` behave like `bundle update --patch` ([#6931](https://github.com/bundler/bundler/pull/6931))
+  - Introduce `Bundler.original_system` and `Bundler.original_exec` to shell out or exec to external programs using the original environment before bundler was loaded ([#7052](https://github.com/bundler/bundler/pull/7052))
+  - Add feature parity to `bundle info GEM` with respect to the old deprecated command `bundle show GEM` [#7026](https://github.com/bundler/bundler/pull/7026)
+  - Introduce `bundle list` to list groups of gems in your Gemfile. This command was actually documented, but was working as an alias to `bundle show` so this could also be considered a bug fix :) [#7072](https://github.com/bundler/bundler/pull/7072)
+  - Introduce `bundle outdated --filter-strict` as an alias to `bundle outdated --strict` [#6030](https://github.com/bundler/bundler/pull/6030)
+  - Add `:git` and `:branch` options to `bundle add` ([#7127](https://github.com/bundler/bundler/pull/7127))
+  - Add `:ruby_26` as a valid value to the `:platform(s)` dsl ([#7155](https://github.com/bundler/bundler/pull/7155))
+  - Let the `bundle cache` command include all features currently provided by `bundle package` ([#7249](https://github.com/bundler/bundler/pull/7249))
+  - Several improvements on new gem templates ([#6924](https://github.com/bundler/bundler/pull/6924), [#6968](https://github.com/bundler/bundler/pull/6968), [#7209](https://github.com/bundler/bundler/pull/7209), [#7222](https://github.com/bundler/bundler/pull/7222), [#7238](https://github.com/bundler/bundler/pull/7238))
+  - Add `--[no-]git` option to `bundle gem` to generate non source control gems. Useful for monorepos, for example ([#7263](https://github.com/bundler/bundler/pull/7263))
+
+Bugfixes:
+
+  - Raise when the same gem is available in multiple sources, and show a suggestion to solve it ([#5985](https://github.com/bundler/bundler/pull/5985))
+  - Validate that bundler has permissions to write to the tmp directory, and raise with a meaningful error otherwise ([#5954](https://github.com/bundler/bundler/pull/5954))
+  - Remove downloaded `.gem` file from the cache if it's corrupted ([#6010](https://github.com/bundler/bundler/pull/6010))
+  - Fix generated README in new gems to explicitly suggest running `bundle install`, so that the outcome is independent from the major version of bundler being run ([#6068](https://github.com/bundler/bundler/pull/6068))
+  - Fix `bundle outdated --group NAME` when the group is listed second in the Gemfile ([#6116](https://github.com/bundler/bundler/pull/6116))
+  - Improve conflict resolution messages by not calling "ruby" a gem when conflict happens in the `required_ruby_version`, and by filtering out requirements that didn't contribute to the conflict ([#6647](https://github.com/bundler/bundler/pull/6647))
+  - Avoid fetching and rebuilding git gems whenever any gem is changed in the Gemfile ([#6711](https://github.com/bundler/bundler/pull/6711))
+  - Include the exact bundler version in the lock file in the suggested command when bundler warns about version mismatches of itself [#6971](https://github.com/bundler/bundler/pull/6971)
+  - Fix plugins being installed every time a command is run #[#6978](https://github.com/bundler/bundler/pull/6978)
+  - Fallback to sequentially fetching specs on 429s [#6728](https://github.com/bundler/bundler/pull/6728)
+  - Make `bundle clean` also clean native extensions for gems with a git source [#7058](https://github.com/bundler/bundler/pull/7058)
+  - Fix `bundle info bundler` to show the correct path to the bundler gem [#7026](https://github.com/bundler/bundler/pull/7026)
+  - Fix `bundle config build.<gem>` not sending multiple parameters to `extconf.rb` correctly [#7023](https://github.com/bundler/bundler/pull/7023)
+  - Fix bad error message on Gemfile errors under ruby 2.7 (still unreleased, but it's a bugfix for beta testers after all) [#7038](https://github.com/bundler/bundler/pull/7038)
+  - Warn about situations where multiple gems provide the same executable ([#7075](https://github.com/bundler/bundler/pull/7075))
+  - Ignore `frozen` setting in inline mode ([#7125](https://github.com/bundler/bundler/pull/7125))
+  - Fix incorrect "bundler attempted to update GEM but version stayed the same" message when updating git sourced gems ([#6325](https://github.com/bundler/bundler/pull/6325))
+  - Don't check for existance of a writable home directory if `BUNDLE_USER_HOME` is set ([#6885](https://github.com/bundler/bundler/pull/6885))
+  - Fix error message when server would respond to a bad username/password requiest with a 401 ([#6928](https://github.com/bundler/bundler/pull/6928))
+  - Fix `bundle outdated` pluralization when multiple groups are requested ([#7063](https://github.com/bundler/bundler/pull/7063))
+  - Fix `bundle install` not updating conservatively when gemspec is changed ([#7143](https://github.com/bundler/bundler/pull/7143))
+  - Fix `bundle exec` not respecting custom process titles inside scripts ([#7140](https://github.com/bundler/bundler/pull/7140))
+  - Fix `bundle update` message about exclude groups saying "installed" instead of "updated" ([#7150](https://github.com/bundler/bundler/pull/7150))
+  - Fix `bundle licenses` not showing correct information about bundler itself ([#7147](https://github.com/bundler/bundler/pull/7147))
+  - Fix installation path not including ruby scope when `BUNDLE_PATH` was set ([#7163](https://github.com/bundler/bundler/pull/7163))
+  - Fix `bundle clean` incorrectly removing git depedencies present in the Gemfile when rubygems 3.0+ was used and path involved a symlink ([#7211](https://github.com/bundler/bundler/pull/7211))
+  - Fix platform specific gems always being re-resolved when bundler was not running under that platform ([#7212](https://github.com/bundler/bundler/pull/7212))
+  - Fix `bundle package --all-platforms` causing `bundle install` to ignore `--with` and `--without` ([#6113](https://github.com/bundler/bundler/pull/6113))
+  - Fix `MissingRevision` git errors to include the specific `git` command that failed under the hood ([#7225](https://github.com/bundler/bundler/pull/7225))
+  - Fix using gemspec & `force_ruby_platform` on Windows ([#6809](https://github.com/bundler/bundler/pull/6809))
+  - Make bundler's binstub checks on bundler version consistent with rubygems `BundlerVersionFinder` ([#7259](https://github.com/bundler/bundler/pull/7259))
+  - Fix `bundle install` and `bundle update` generating different lockfiles when `path:` gems with relative paths starting with "./" were used ([#7264](https://github.com/bundler/bundler/pull/7264))
+  - Give a proper error when user tries to `bundle open` a default gem ([#7288](https://github.com/bundler/bundler/pull/7288))
+  - Fix `bundle doctor` command ([#7309](https://github.com/bundler/bundler/pull/7309))
+  - Fix bundler giving an unclear recommendation when duplicated gems are found in the Gemfile ([#7302](https://github.com/bundler/bundler/pull/7302))
+
+Documentation:
+
+  - Fix typo on a file extension in `bundle.ronn` [#7146](https://github.com/bundler/bundler/pull/7146)
+  - Fix incorrect default value for `cache_path` configuration ([#7229](https://github.com/bundler/bundler/pull/7229))
+  - Binstubs documentation has been improved ([#5889](https://github.com/bundler/bundler/pull/5889))
+  - Fix incorrect sections when explaining `:git`, `:branch`, and `:ref` options ([#7265](https://github.com/bundler/bundler/pull/7265))
+  - Fix mentions to remembered options in docs to explain the current state ([#7242](https://github.com/bundler/bundler/pull/7242))
+
+Internally, there's also been a bunch of improvements in our development
+environment, test suite, policies, contributing docs, and a bunch of cleanups of
+old compatibility code.
+
 ## 2.0.2 (2019-06-13)
 
 Changes:
@@ -63,8 +161,8 @@ Note: To upgrade your Gemfile to Bundler 2 you will need to run `bundle update -
 
 Breaking Changes:
 
-  - Dropped support for versions of Ruby < 2.3
-  - Dropped support for version of RubyGems < 2.5
+  - Dropped support for versions of Ruby under 2.3
+  - Dropped support for version of RubyGems under 2.5
   - Moved error messages from STDOUT to STDERR
 
 Note: To upgrade your Gemfile to Bundler 2 you will need to run `bundle update --bundler`
@@ -2812,7 +2910,7 @@ isolation.
   - Fixes an obscure bug where switching the source of a gem could fail to correctly
     change the source of its dependencies
   - Support multiple version dependencies in the Gemfile
-    (gem "rails", ">= 3.0.0.beta1", "<= 3.0.0")
+    (`gem "rails", ">= 3.0.0.beta1", "<= 3.0.0"`)
   - Raise an exception for ambiguous uses of multiple declarations of the same gem
     (for instance, with different versions or sources).
   - Fix cases where the same dependency appeared several times in the Gemfile.lock
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000000..30d326795e
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,229 @@
+# Upgrading
+
+## Bundler 3
+
+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 will be printed by default in the upcoming
+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 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 three groups: CLI 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
+that we plan to make to this set of commands and options.
+
+* Flags passed to `bundle install` that relied on being remembered across invokations have been deprecated.
+
+  In particular, the `--clean`, `--deployment`, `--frozen`, `--no-cache`,
+  `--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 accross exactly the same invokations _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` invokations 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 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.
+
+* `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](https://github.com/bundler/bundle-viz) that it's officially maintained
+  by the bundler team, and that users can take as a reference to develop their
+  own plugins. The plugin contains the same code as the old core command, the
+  only difference being that the command is now implemented as `bundle graph`
+  hich is much easier to understand. Have a look at the plugin's repo for more
+  information about how to install and use the new plugin.
+
+* The `bundle console` will be removed and replaced with `bin/console`.
+
+  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 maintainance 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.
+
+* The `bundle update` command will no longer update all gems, you'll need to pass `--all` to it.
+
+  The bundler team considers that updating all gems at once should not be the
+  main use case for this command, and that it's better to upgrade gems one at a
+  time (or in groups of related gems). You can still upgrade all gems at once,
+  but now you need the `--all` flag.
+
+* 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
+  must be created and checked into version control individually.
+
+* The `bundle config` command has a new subcommand-based interface.
+
+  We believe the old interface where the kind of operation was guessed from the
+  combination of flags and number of arguments being passed to the command was
+  confusing. Instead we have introduced a compulsory subcommand argument that
+  can be either `list`, `get`, `set` or `unset`. We believe this will make the
+  `config` command much easier to interact with. The old interface is
+  deprecated, but we are giving suggestions about the new commands that should
+  be used along with the deprecation messages.
+
+* The `bundle inject` command is deprecated and 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.
+
+#### Helper deprecations
+
+* `Bundler.clean_env`, `Bundler.with_clean_env`, `Bundler.clean_system`, and `Bundler.clean_exec` are deprecated.
+
+  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.
+
+* Multiple global Gemfile sources will no longer be supported.
+
+  Instead of something like this:
+
+  ```ruby
+  source "https://main_source"
+  source "https://another_source"
+
+  gem "dependency1"
+  gem "dependency2"
+  ```
+
+  do something like this:
+
+  ```ruby
+  source "https://main_source"
+
+  gem "dependency1"
+
+  source "https://another_source" do
+    gem "dependency2"
+  end
+  ```
+
+* Global `path` and `git` sources will no longer be supported.
+
+  Instead of something like this:
+
+  ```ruby
+  path "/my/path/with/gems"
+  git "https://my_git_repo_with_gems"
+
+  gem "dependency1"
+  gem "dependency2"
+  ```
+
+  do something like this:
+
+  ```ruby
+  gem "dependency1", path: "/my/path/with/gems"
+  gem "dependency2", git: "https://my_git_repo_with_gems"
+  ```
+
+  or use the block forms if you have multiple gems for each source and you want
+  to be a bit DRYer:
+
+
+  ```ruby
+  path "/my/path/with/gems" do
+    # gem "dependency1"
+    # ...
+    # gem "dependencyn"
+  end
+
+  git "https://my_git_repo_with_gems" do
+    # gem "dependency1"
+    # ...
+    # gem "dependencyn"
+  end
+  ```
+
+#### Misc deprecations
+
+* Deployment helpers for `vlad` and `capistrano` are being removed.
+
+  These are natural deprecations since the `vlad` tool has had no activity for
+  years whereas `capistrano` 3 has built-in Bundler integration in the form of
+  the `capistrano-bundler` gem, and everyone using Capistrano 3 should be
+  already using that instead. If for some reason, you are still using Capistrano
+  2, feel free to copy the Capistrano tasks out of the Bundler 2 file
+  `bundler/deployment.rb` and put them into your app.
+
+  In general, we don't want to maintain integrations for every deployment system
+  out there, so that's why we are removing these.