One round of self-feedback

This should be ready now.

2 files changed, 30 insertions, 34 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 61ad4e1d4c..3f2a6f742c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,9 +1,10 @@
 ## 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 out by default. We do this to grab
-feedback and comunicate early to our users to kind of changes we're intending to
-make in bundler 3. See [#6965](https://github.com/bundler/bundler/pull/6965).
+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
@@ -37,11 +38,11 @@ Features:
   - 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)
-  - `bundle list` is introduced to list groups of gems in your Gemfile. This command was actually documented, but was just 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 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))
-  - `bundle cache` now includes all features provided by `bundle package` ([#7249](https://github.com/bundler/bundler/pull/7249))
+  - 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))
 
@@ -52,9 +53,9 @@ Bugfixes:
   - 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))
+  - 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 warnings about version mismatches of itself [#6971](https://github.com/bundler/bundler/pull/6971)
+  - 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)
@@ -63,21 +64,21 @@ Bugfixes:
   - 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" when updating git sourced gems ([#6325](https://github.com/bundler/bundler/pull/6325))
+  - 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 show correct information about bundler itself ([#7147](https://github.com/bundler/bundler/pull/7147))
+  - 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))
-  - bundler's binstub checks on bundler version are now consisten with rubygems `BundlerVersionFinder` ([#7259](https://github.com/bundler/bundler/pull/7259))
+  - 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))
diff --git a/UPGRADING.md b/UPGRADING.md
index 4a7e5c55e7..30d326795e 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -53,24 +53,27 @@ that we plan to make to this set of commands and options.
   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 renaming of the flag, to make more apparent what it
+  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) a gem dependency (the `ruby-graphviz`
+  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 contains 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. Have a look
-  at https://github.com/bundler/bundle-viz for more information about how to
-  install and use the new plugin.
+  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`.
 
@@ -80,23 +83,15 @@ that we plan to make to this set of commands and options.
   in favor of a `bin/console` script created by `bundle gem` on gem generation
   that users can tweak to their needs.
 
-  [NOTE: Should we provide an easy way to add `bin/console` to an existing gem?]
-
 * The `bundle update` command will no longer update all gems, you'll need to pass `--all` to it.
 
-  [NOTE: I'm not elaborating on this change yet because I have hesitations about
-  it which I've mentioned in https://github.com/bundler/bundler/pull/7008. After
-  reading up on it a bit more and seeing that it all starts with "many people
-  think that they should run bundle update after git pull", I wonder even more.
-  Why is this? Isn't this a documentation issue that shouldn't make us change
-  bundler?]
+  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.
 
-  [NOTE: I'm not sure if I got the rationale for this one right, and I couln't
-  find any related Github discussion other than an upgrading document in the
-  2-0-stable flag that mentions it. Please double check this]
-
   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
@@ -201,7 +196,9 @@ unambiguously defined.
   gem "dependency2", git: "https://my_git_repo_with_gems"
   ```
 
-  or use the block forms:
+  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
@@ -217,8 +214,6 @@ unambiguously defined.
   end
   ```
 
-  if you have multiple gems for each source and you want to be a bit DRYer.
-
 #### Misc deprecations
 
 * Deployment helpers for `vlad` and `capistrano` are being removed.