Auto merge of #5108 - chrismo:cons_update_docs, r=indirect

[WIP] New patch level and conservative options documented.

Fixes #4775.

6 files changed, 313 insertions, 29 deletions

diff --git a/lib/bundler/cli.rb b/lib/bundler/cli.rb
index 37556f4926..f618f5cb58 100644
--- a/lib/bundler/cli.rb
+++ b/lib/bundler/cli.rb
@@ -222,9 +222,9 @@ module Bundler
     method_option "major", :type => :boolean, :banner =>
       "Prefer updating to next major version (default)"
     method_option "strict", :type => :boolean, :banner =>
-      "Do not allow any gem to be updated past latest --patch/--minor/--major"
+      "Do not allow any gem to be updated past latest --patch | --minor | --major"
     method_option "conservative", :type => :boolean, :banner =>
-      "Use bundle install conservative update behavior and do not allowed shared dependencies to be updated."
+      "Use bundle install conservative update behavior and do not allow shared dependencies to be updated."
     def update(*gems)
       require "bundler/cli/update"
       Update.new(options, gems).run
@@ -271,8 +271,8 @@ module Bundler
       versions of the given gems. Prerelease gems are ignored by default. If your gems
       are up to date, Bundler will exit with a status of 0. Otherwise, it will exit 1.
 
-      For more information on conservative resolution options (--major, --minor,
-      --patch, --strict) see documentation on the same options on the update command.
+      For more information on patch level options (--major, --minor, --patch,
+      --update-strict) see documentation on the same options on the update command.
     D
     method_option "group", :aliases => "--group", :type => :string, :banner => "List gems from a specific group"
     method_option "groups", :aliases => "--groups", :type => :boolean, :banner => "List gems organized by groups"
@@ -283,7 +283,7 @@ module Bundler
     method_option "strict", :type => :boolean, :banner =>
       "Only list newer versions allowed by your Gemfile requirements"
     method_option "update-strict", :type => :boolean, :banner =>
-      "Strict conservative resolution, do not allow any gem to be updated past latest --patch/--minor/--major"
+      "Strict conservative resolution, do not allow any gem to be updated past latest --patch | --minor | --major"
     method_option "minor", :type => :boolean, :banner => "Prefer updating only to next minor version"
     method_option "major", :type => :boolean, :banner => "Prefer updating to next major version (default)"
     method_option "patch", :type => :boolean, :banner => "Prefer updating only to next patch version"
@@ -466,9 +466,9 @@ module Bundler
     method_option "full-index", :type => :boolean, :default => false, :banner =>
       "Fall back to using the single-file index of all gems"
     method_option "add-platform", :type => :array, :default => [], :banner =>
-      "add a new platform to the lockfile"
+      "Add a new platform to the lockfile"
     method_option "remove-platform", :type => :array, :default => [], :banner =>
-      "remove a platform from the lockfile"
+      "Remove a platform from the lockfile"
     method_option "patch", :type => :boolean, :banner =>
       "If updating, prefer updating only to next patch version"
     method_option "minor", :type => :boolean, :banner =>
@@ -478,7 +478,7 @@ module Bundler
     method_option "strict", :type => :boolean, :banner =>
       "If updating, do not allow any gem to be updated past latest --patch | --minor | --major"
     method_option "conservative", :type => :boolean, :banner =>
-      "If updating, use bundle install conservative update behavior and do not allowed shared dependencies to be updated."
+      "If updating, use bundle install conservative update behavior and do not allow shared dependencies to be updated"
     def lock
       require "bundler/cli/lock"
       Lock.new(options).run
diff --git a/man/bundle-lock.ronn b/man/bundle-lock.ronn
index 8afc50af8a..b18d819c21 100644
--- a/man/bundle-lock.ronn
+++ b/man/bundle-lock.ronn
@@ -7,6 +7,14 @@ bundle-lock(1) -- Creates / Updates a lockfile without installing
               [--local]
               [--print]
               [--lockfile=PATH]
+              [--full-index]
+              [--add-platform]
+              [--remove-platform]
+              [--patch]
+              [--minor]
+              [--major]
+              [--strict]
+              [--conservative]
 
 ## DESCRIPTION
 
@@ -30,6 +38,30 @@ Lock the gems specified in Gemfile.
 * `--lockfile=<path>`:
   The path where the lockfile should be written to.
 
+* `--full-index`:
+  Fall back to using the single-file index of all gems.
+
+* `--add-platform`:
+  Add a new platform to the lockfile.
+
+* `--remove-platform`:
+  Remove a platform from the lockfile.
+
+* `--patch`:
+  If updating, prefer updating only to next patch version.
+
+* `--minor`:
+  If updating, prefer updating only to next minor version.
+
+* `--major`:
+  If updating, prefer updating to next major version (default).
+
+* `--strict`:
+  If updating, do not allow any gem to be updated past latest --patch | --minor | --major.
+
+* `--conservative`:
+  If updating, use bundle install conservative update behavior and do not allow shared dependencies to be updated.
+
 ## UPDATING ALL GEMS
 
 If you run `bundle lock` with `--update` option without list of gems, bundler will
@@ -45,3 +77,7 @@ For instance, you only want to update `nokogiri`, run `bundle lock --update noko
 
 Bundler will update `nokogiri` and any of its dependencies, but leave the rest of the
 gems that you specified locked to the versions in the `Gemfile.lock`.
+
+## PATCH LEVEL OPTIONS
+
+See [bundle update(1)][bundle-update] for details.
diff --git a/man/bundle-outdated.ronn b/man/bundle-outdated.ronn
new file mode 100644
index 0000000000..47792e61b2
--- /dev/null
+++ b/man/bundle-outdated.ronn
@@ -0,0 +1,107 @@
+bundle-outdated(1) -- List installed gems with newer versions available
+=======================================================================
+
+## SYNOPSIS
+
+`bundle outdated` [GEM] [--local]
+                        [--pre]
+                        [--source]
+                        [--strict]
+                        [--parseable | --porcelain]
+                        [--group=GROUP]
+                        [--groups]
+                        [--update-strict]
+                        [--patch|--minor|--major]
+                        [--filter-major]
+                        [--filter-minor]
+                        [--filter-patch]
+
+## DESCRIPTION
+
+Outdated lists the names and versions of gems that have a newer version available
+in the given source. Calling outdated with [GEM [GEM]] will only check for newer
+versions of the given gems. Prerelease gems are ignored by default. If your gems
+are up to date, Bundler will exit with a status of 0. Otherwise, it will exit 1.
+
+## OPTIONS
+
+* `--local`:
+  Do not attempt to fetch gems remotely and use the gem cache instead.
+
+* `--pre`:
+  Check for newer pre-release gems.
+
+* `--source`:
+  Check against a specific source.
+
+* `--strict`:
+  Only list newer versions allowed by your Gemfile requirements.
+
+* `--parseable`:
+   Use minimal formatting for more parseable output.
+
+* `--group`:
+  List gems from a specific group.
+
+* `--groups`:
+  List gems organized by groups.
+
+* `--update-strict`:
+  Strict conservative resolution, do not allow any gem to be updated past latest --patch | --minor| --major.
+
+* `--minor`:
+  Prefer updating only to next minor version.
+
+* `--major`:
+  Prefer updating to next major version (default).
+
+* `--patch`:
+  Prefer updating only to next patch version.
+
+* `--filter-major`:
+  Only list major newer versions.
+
+* `--filter-minor`:
+  Only list minor newer versions.
+
+* `--filter-patch`:
+  Only list patch newer versions.
+
+## PATCH LEVEL OPTIONS
+
+See [bundle update(1)][bundle-update] for details.
+
+One difference between the patch level options in `bundle update` and here is the `--strict` option.
+`--strict` was already an option on outdated before the patch level options were added. `--strict`
+wasn't altered, and the `--update-strict` option on `outdated` reflects what `--strict` does on
+`bundle update`.
+
+## FILTERING OUTPUT
+
+The 3 filtering options do not affect the resolution of versions, merely what versions are shown
+in the output.
+
+If the regular output shows the following:
+
+    * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test"
+    * hashie (newest 3.4.6, installed 1.2.0, requested = 1.2.0) in groups "default"
+    * headless (newest 2.3.1, installed 2.2.3) in groups "test"
+
+`--filter-major` would only show:
+
+    * hashie (newest 3.4.6, installed 1.2.0, requested = 1.2.0) in groups "default"
+
+`--filter-minor` would only show:
+
+    * headless (newest 2.3.1, installed 2.2.3) in groups "test"
+
+`--filter-patch` would only show:
+
+    * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test"
+
+Filter options can be combined. `--filter-minor` and `--filter-patch` would show:
+
+    * faker (newest 1.6.6, installed 1.6.5, requested ~> 1.4) in groups "development, test"
+    * headless (newest 2.3.1, installed 2.2.3) in groups "test"
+
+Combining all three `filter` options would be the same result as providing none of them.
diff --git a/man/bundle-update.ronn b/man/bundle-update.ronn
index 47d70f661c..7986a17bdc 100644
--- a/man/bundle-update.ronn
+++ b/man/bundle-update.ronn
@@ -3,7 +3,18 @@ bundle-update(1) -- Update your gems to the latest available versions
 
 ## SYNOPSIS
 
-`bundle update` <*gems> [--group=NAME] [--source=NAME] [--local] [--ruby]
+`bundle update` <*gems> [--group=NAME]
+                        [--source=NAME]
+                        [--local]
+                        [--ruby]
+                        [--bundler[=VERSION]]
+                        [--full-index]
+                        [--jobs=JOBS]
+                        [--quiet]
+                        [--force]
+                        [--patch|--minor|--major]
+                        [--strict]
+                        [--conservative]
 
 ## DESCRIPTION
 
@@ -37,6 +48,33 @@ gem.
 * `--bundler`:
   Update the locked version of bundler to the invoked bundler version.
 
+* `--full-index`:
+  Fall back to using the single-file index of all gems.
+
+* `--jobs`:
+  Specify the number of jobs to run in parallel.
+
+* `--quiet`:
+  Only output warnings and errors.
+
+* `--force`:
+  Force downloading every gem.
+
+* `--patch`:
+  Prefer updating only to next patch version.
+
+* `--minor`:
+  Prefer updating only to next minor version.
+
+* `--major`:
+  Prefer updating to next major version (default).
+
+* `--strict`:
+  Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`.
+
+* `--conservative`:
+  Use bundle install conservative update behavior and do not allow shared dependencies to be updated.
+
 ## UPDATING ALL GEMS
 
 If you run `bundle update` with no parameters, bundler will ignore
@@ -146,14 +184,125 @@ In this case, the two gems have their own set of dependencies, but they share
 `bundle update thin` will update `rack` even though it's _also_ a dependency of
 `rack-perftools_profiler`.
 
-`In short`, when you update a gem using `bundle update`, bundler will update all
-dependencies of that gem, including those that are also dependencies of another gem.
+In short, by default, when you update a gem using `bundle update`, bundler will
+update all dependencies of that gem, including those that are also dependencies
+of another gem.
+
+To prevent updating shared dependencies, prior to version 1.14 the only option
+was the `CONSERVATIVE UPDATING` behavior in [bundle install(1)][bundle-install]:
 
 In this scenario, updating the `thin` version manually in the Gemfile(5),
 and then running [bundle install(1)][bundle-install] will only update `daemons` and `eventmachine`,
 but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section
 of [bundle install(1)][bundle-install].
 
+Starting with 1.14, specifying the `--conservative` option will also prevent shared
+dependencies from being updated.
+
+## PATCH LEVEL OPTIONS
+
+Version 1.14 introduced 4 patch-level options that will influence how gem
+versions are resolved. One of the following options can be used: `--patch`,
+`--minor` or `--major`. `--strict` can be added to further influence resolution.
+
+* `--patch`:
+  Prefer updating only to next patch version.
+
+* `--minor`:
+  Prefer updating only to next minor version.
+
+* `--major`:
+  Prefer updating to next major version (default).
+
+* `--strict`:
+  Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`.
+
+When Bundler is resolving what versions to use to satisfy declared
+requirements in the Gemfile or in parent gems, it looks up all
+available versions, filters out any versions that don't satisfy
+the requirement, and then, by default, sorts them from newest to
+oldest, considering them in that order.
+
+Providing one of the patch level options (e.g. `--patch`) changes the
+sort order of the satisfying versions, causing Bundler to consider the
+latest `--patch` or `--minor` version available before other versions.
+Note that versions outside the stated patch level could still be
+resolved to if necessary to find a suitable dependency graph.
+
+For example, if gem 'foo' is locked at 1.0.2, with no gem requirement
+defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0
+all exist, the default order of preference by default (`--major`) will
+be "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
+
+If the `--patch` option is used, the order of preference will change to
+"1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
+
+If the `--minor` option is used, the order of preference will change to
+"1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
+
+Combining the `--strict` option with any of the patch level options
+will remove any versions beyond the scope of the patch level option,
+to ensure that no gem is updated that far.
+
+To continue the previous example, if both `--patch` and `--strict`
+options are used, the available versions for resolution would be
+"1.0.4, 1.0.3, 1.0.2". If `--minor` and `--strict` are used, it would
+be "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
+
+Gem requirements as defined in the Gemfile will still be the first
+determining factor for what versions are available. If the gem
+requirement for `foo` in the Gemfile is '~> 1.0', that will accomplish
+the same thing as providing the `--minor` and `--strict` options.
+
+## PATCH LEVEL EXAMPLES
+
+Given the following gem specifications:
+
+    foo 1.4.3, requires: ~> bar 2.0
+    foo 1.4.4, requires: ~> bar 2.0
+    foo 1.4.5, requires: ~> bar 2.1
+    foo 1.5.0, requires: ~> bar 2.1
+    foo 1.5.1, requires: ~> bar 3.0
+    bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
+
+Gemfile:
+
+    gem 'foo'
+
+Gemfile.lock:
+
+    foo (1.4.3)
+      bar (~> 2.0)
+    bar (2.0.3)
+
+Cases:
+
+    #  Command Line                     Result
+    ------------------------------------------------------------
+    1  bundle update --patch            'foo 1.4.5', 'bar 2.1.1'
+    2  bundle update --patch foo        'foo 1.4.5', 'bar 2.1.1'
+    3  bundle update --minor            'foo 1.5.1', 'bar 3.0.0'
+    4  bundle update --minor --strict   'foo 1.5.0', 'bar 2.1.1'
+    5  bundle update --patch --strict   'foo 1.4.4', 'bar 2.0.4'
+
+In case 1, bar is upgraded to 2.1.1, a minor version increase, because
+the dependency from foo 1.4.5 required it.
+
+In case 2, only foo is requested to be unlocked, but bar is also
+allowed to move because it's not a declared dependency in the Gemfile.
+
+In case 3, bar goes up a whole major release, because a minor increase
+is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
+of bar.
+
+In case 4, foo is preferred up to a minor version, but 1.5.1 won't work
+because the --strict flag removes bar 3.0.0 from consideration since
+it's a major increment.
+
+In case 5, both foo and bar have any minor or major increments removed
+from consideration because of the --strict flag, so the most they can
+move is up to 1.4.4 and 2.0.4.
+
 ## RECOMMENDED WORKFLOW
 
 In general, when working with an application managed with bundler, you should
diff --git a/spec/commands/update_spec.rb b/spec/commands/update_spec.rb
index f5c155e73a..63fe951c43 100644
--- a/spec/commands/update_spec.rb
+++ b/spec/commands/update_spec.rb
@@ -526,8 +526,6 @@ describe "bundle update conservative" do
 
         expect(the_bundle).to include_gems "foo 1.4.5", "bar 2.1.1", "qux 1.0.1"
       end
-
-      it "warns on minor or major increment elsewhere" ## include in prior test
     end
 
     context "minor preferred" do
@@ -536,10 +534,6 @@ describe "bundle update conservative" do
 
         expect(the_bundle).to include_gems "foo 1.5.1", "bar 3.0.0", "qux 1.0.0"
       end
-
-      it "warns on major increment elsewhere" ## include in prior test
-
-      it "warns when something unlocked doesn't update at all"
     end
 
     context "strict" do
@@ -652,10 +646,4 @@ describe "bundle update conservative" do
       expect(out).to eq "Provide only one of the following options: minor, patch"
     end
   end
-
-  context "other commands" do
-    it "Installer could support --dry-run flag for install and update"
-
-    it "outdated should conform its flags to the resolver flags"
-  end
 end
diff --git a/spec/resolver/basic_spec.rb b/spec/resolver/basic_spec.rb
index 3e8883d1d4..e3187726fd 100644
--- a/spec/resolver/basic_spec.rb
+++ b/spec/resolver/basic_spec.rb
@@ -214,18 +214,22 @@ describe "Resolving" do
         should_conservative_resolve_and_include :patch, [], %w(foo-1.4.4 bar-2.1.1)
       end
 
-      it "will not revert to a previous version in strict mode level patch" do
-        pending "possible issue with molinillo - needs further research"
-        should_conservative_resolve_and_include [:patch, :strict], [], %w(foo-1.4.3 bar-2.1.1)
+      it "cannot revert to a previous version in strict mode level patch" do
+        # the strict option removes the version required to match, so a version conflict results
+        expect do
+          should_conservative_resolve_and_include [:patch, :strict], [], %w(foo-1.4.3 bar-2.1.1)
+        end.to raise_error Bundler::VersionConflict, /#{Regexp.escape("Could not find gem 'bar (~> 2.1.0)'")}/
       end
 
       it "could revert to a previous version level minor" do
         should_conservative_resolve_and_include :minor, [], %w(foo-1.5.0 bar-2.0.5)
       end
 
-      it "will not revert to a previous version in strict mode level minor" do
-        pending "possible issue with molinillo - needs further research"
-        should_conservative_resolve_and_include [:minor, :strict], [], %w(foo-1.4.3 bar-2.1.1)
+      it "cannot revert to a previous version in strict mode level minor" do
+        # the strict option removes the version required to match, so a version conflict results
+        expect do
+          should_conservative_resolve_and_include [:minor, :strict], [], %w(foo-1.4.3 bar-2.1.1)
+        end.to raise_error Bundler::VersionConflict, /#{Regexp.escape("Could not find gem 'bar (~> 2.0.0)'")}/
       end
     end
   end