bundler-patch 0.10.4 → 1.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 621d370daa4220636771b1cdada19350d866797f
-  data.tar.gz: 694a377520e067ecc93690a7c7036f5046dc1702
+  metadata.gz: 28562c56f8a370cf07b84a98031b022906c83302
+  data.tar.gz: c8402af554da11c8e0296e9ded6f0d32221bc6b0
 SHA512:
-  metadata.gz: df7910ec37f1ffd133e688db6d4252b3dac4d46ef52f311716f053c6b6a8cf35b5349643469aec956847497ace476415965e41dab5c4b32de01e3dd1163605df
-  data.tar.gz: dbcbfed4101b53ff2209768ed4f05db5913f1d5380a64fd85a96309b4d30715fbb96d97e7fcf710a58f57d0d3436b4605e8e4087f60c11a339def376be5e68b5
+  metadata.gz: f6662076fad605bad8b8b01c0de0ab948416359ef80648a12b955e9911941ce230cd70cdb07e3f2fa19b52334577af091532fc80e08b89f58852c8ff6d66b8d5
+  data.tar.gz: cccc7f7319d86baa566f7121b1869036ee8d52f7a1a15ebf17d373f2c989896eedc98d03ec707d38ec8741bb0e1e799eb70b8ad2b6622c6c83dbeb18491e8303

data/.travis.yml

@@ -9,19 +9,21 @@ script: bundle exec rake test:all
 
 matrix:
   include:
-    - rvm: 2.1.10
-      env: BUNDLER_TEST_VERSION=1.12.5
-    - rvm: 2.2.5
-      env: BUNDLER_TEST_VERSION=1.12.5
-    - rvm: 2.3.1
+    - rvm: 2.3.4
       env: BUNDLER_TEST_VERSION=1.9.10
-    - rvm: 2.3.1
+    - rvm: 2.3.4
       env: BUNDLER_TEST_VERSION=1.10.5
-    - rvm: 2.3.1
+    - rvm: 2.3.4
       env: BUNDLER_TEST_VERSION=1.11.2
-    - rvm: 2.3.1
+    - rvm: 2.3.4
       env: BUNDLER_TEST_VERSION=1.12.5
-    - rvm: 2.3.1
-      env: BUNDLER_TEST_VERSION=1.13.5
-    - rvm: 2.3.3
-      env: BUNDLER_TEST_VERSION=1.14.3
+    - rvm: 2.3.4
+      env: BUNDLER_TEST_VERSION=1.13.6
+    - rvm: 2.3.4
+      env: BUNDLER_TEST_VERSION=1.14.6
+    - rvm: 2.1.10
+      env: BUNDLER_TEST_VERSION=1.15.0
+    - rvm: 2.2.7
+      env: BUNDLER_TEST_VERSION=1.15.0
+    - rvm: 2.3.4
+      env: BUNDLER_TEST_VERSION=1.15.0

data/README.md

@@ -3,14 +3,21 @@
 `bundler-patch` can update your gems conservatively to deal with vulnerable
 gems or just get more current.
 
-By default, "conservatively" means it will prefer the latest releases from the
-current version, over the latest minor releases or the latest major releases.
-This is somewhat opposite from `bundle update` which prefers newest/major
-versions first.
+By default, "conservatively" means it will prefer the latest patch releases
+from the current version, over the latest minor releases or the latest major
+releases. This is somewhat opposite from `bundle update` which prefers
+newest/major versions first.
+
+Works with Bundler 1.9 and higher. Starting with Bundler 1.14 (undocumented in
+1.13), much of the core behavior in `bundler-patch` has been ported to Bundler
+itself. See [Patch Level
+Options](http://bundler.io/v1.14/man/bundle-update.1.html#PATCH-LEVEL-OPTIONS),
+[Overlapping
+Dependencies](http://bundler.io/v1.14/man/bundle-update.1.html#OVERLAPPING-DEPENDENCIES) 
+in the `bundle update` docs, also [Patch Level 
+Options](http://bundler.io/v1.14/man/bundle-outdated.1.html#PATCH-LEVEL-OPTIONS)
+in the `bundle outdated` docs.
 
-Works with Bundler 1.9 and higher. Starting with Bundler 1.13, much of the
-core behavior in `bundler-patch` has been ported to Bundler itself. Read 
-[BUNDLER.md](BUNDLER.md) for more information.
 
 [![Build Status](https://travis-ci.org/livingsocial/bundler-patch.svg?branch=master)](https://travis-ci.org/livingsocial/bundler-patch)
 
@@ -30,14 +37,15 @@ made.
 
     $ bundle patch
 
-"Conservatively" means it will sort all available versions to prefer the
-latest releases from the current version, then the latest minor releases and
+"Conservatively" means it will sort all available versions to prefer the latest
+patch releases from the current version, then the latest minor releases and
 then the latest major releases.
 
 "Prefer" means that no available versions are removed from consideration*, to
 help ensure a suitable dependency graph can be reconciled. This does mean some
-gems cannot be upgraded or may be upgraded to unexpected versions. NOTE: There is
-a `--strict_updates` option which _will_ remove versions from consideration, see below.
+gems cannot be upgraded or may be upgraded to unexpected versions. NOTE: There
+is a `--strict` option which _will_ remove versions from consideration,
+see below.
 
 _*That's a white-lie. bundler-patch will actually remove from consideration
 any versions older than the currently locked version, which `bundle update`
@@ -45,8 +53,9 @@ will not do. It's not common, but it is possible for `bundle update` to
 regress a gem to an older version, if necessary to reconcile the dependency
 graph._
 
-Gem requirements as defined in the Gemfile will still define what versions are available.
-The new conservative behavior controls the preference order of those versions.
+Gem requirements as defined in the Gemfile will still define what versions are
+available. The new conservative behavior controls the preference order of those
+versions.
 
 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
@@ -62,18 +71,17 @@ gems.
 
     $ bundle patch foo bar
 
-  * `-m/--minor_preferred` option will give preference for minor versions over
-    release versions.
+  * `-m/--minor` option will give preference for minor versions over patch
+    versions.
 
-  * `-p/--prefer_minimal` option will reverse the preference order within
-    release, minor, major groups to just 'the next' version. In the prior
-    example, the order of preference changes to "1.0.3, 1.0.4, 1.0.2, 1.1.0,
-    1.1.1, 2.0.0"
+  * `-n/--minimal` option will reverse the preference order within patch,
+    minor, major groups to just 'the next' version. In the prior example, the
+    order of preference changes to "1.0.3, 1.0.4, 1.0.2, 1.1.0, 1.1.1, 2.0.0"
 
-  * `-s/--strict_updates` option will actually remove from consideration
-    versions outside either the current release (or minor version if `-m`
-    specified). This increases the chances of Bundler being unable to
-    reconcile the dependency graph and could raise a `VersionConflict`.
+  * `-s/--strict` option will actually remove from consideration versions
+    outside either the current patch version (or minor version if `-m`
+    specified). This increases the chances of Bundler being unable to reconcile
+    the dependency graph and could raise a `VersionConflict`.
 
 `bundler-patch` will also check for vulnerabilities based on the
 `ruby-advisory-db`, but also will _modify_ (if necessary) the gem requirement
@@ -82,22 +90,36 @@ in the Gemfile on vulnerable gems to ensure they can be upgraded.
   * `-l/--list` option will just list vulnerable gems. No updates will be
     performed.
 
-  * `-a/--advisory_db_path` option can provide the path to an additional
+  * `-a/--advisory-db-path` option can provide the path to an additional
     custom ruby-advisory-db styled directory. The path should not include the
     final `gems` directory, that will be appended automatically. This can be
     used for flagging necessary updates for custom/internal gems.
+    
+  * `-d/--ruby-advisory-db-path` option can override the default path where the
+    ruby-advisory-db repository is checked out into.
 
 The rules for updating vulnerable gems are almost identical to the general
 `bundler-patch` behavior described above, and abide by the same options (`-m`,
-`-p`, and `-s`) though there are some tweaks to encourage getting to at least
+`-n`, and `-s`) though there are some tweaks to encourage getting to at least
 a patched version of the gem. Keep in mind Bundler may still choose unexpected
 versions in order to satisfy the dependency graph.
 
-   * `-v/--vulnerable_gems_only` option will automatically restrict the gems
+   * `-v/--vulnerable-gems-only` option will automatically restrict the gems
      to update list to currently vulnerable gems. If a combination of `-v` and
      a list of gem names are passed, the `-v` option is ignored in favor of
      the listed gem names.
 
+`bundler-patch` can also update the Ruby version listed in .ruby-version and
+the Gemfile if given a list of the latest Ruby versions that are available with
+the following options. Jumps of major versions will not be made at all and this
+feature is designed such that the version will be updated to only the next
+available in the list. If the current version is 2.3.1, and the list of
+`--rubies` is "2.3.2, 2.3.3", then 2.3.2 will be used, not 2.3.3. The intention
+is for this list to be only the most recent version(s) of Ruby supported, (e.g.
+"2.1.10, 2.2.7, 2.3.4").
+ 
+   * `-r/--ruby` option indicates updates to Ruby version will be made.
+   * `--rubies` a comma-delimited list of target Ruby versions to upgrade to. 
 
 ## Examples
 
@@ -107,8 +129,8 @@ versions in order to satisfy the dependency graph.
 |-------------|---------|-----------------------------|----------|--------|
 | foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  |          | 1.4.5  |
 | foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  | -m       | 1.5.1  |
-| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  | -p       | 1.4.4  |
-| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  | -m -p    | 1.5.0  |
+| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  | -n       | 1.4.4  |
+| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1  | -m -n    | 1.5.0  |
 
 ### Two Gems
 
@@ -131,21 +153,24 @@ Gemfile.lock:
       bar (~> 2.0)
     bar (2.0.3)
 
-| # | Command Line              | Result                    |
-|---|---------------------------|---------------------------|
-| 1 | bundle patch              | 'foo 1.4.5', 'bar 2.1.1'  |
-| 2 | bundle patch foo          | 'foo 1.4.4', 'bar 2.0.3'  |
-| 3 | bundle patch -m           | 'foo 1.5.1', 'bar 3.0.0'  |
-| 4 | bundle patch -m -s        | 'foo 1.5.0', 'bar 2.1.1'  |
-| 5 | bundle patch -s           | 'foo 1.4.4', 'bar 2.0.4'  |
-| 6 | bundle patch -p           | 'foo 1.4.4', 'bar 2.0.4'  |
-| 7 | bundle patch -p -m        | 'foo 1.5.0', 'bar 2.1.0'  |
+| # | Command Line                    | Result                    |
+|---|---------------------------------|---------------------------|
+| 1 | bundle patch                    | 'foo 1.4.5', 'bar 2.1.1'  |
+| 2 | bundle patch foo                | 'foo 1.4.5', 'bar 2.1.1'  |
+| 3 | bundle patch --minor            | 'foo 1.5.1', 'bar 3.0.0'  |
+| 4 | bundle patch --minor --strict   | 'foo 1.5.0', 'bar 2.1.1'  |
+| 5 | bundle patch --strict           | 'foo 1.4.4', 'bar 2.0.4'  |
+| 6 | bundle patch --minimal          | 'foo 1.4.4', 'bar 2.0.4'  |
+| 7 | bundle patch --strict foo       | 'foo 1.4.4', 'bar 2.0.3'  |
+| 8 | bundle patch --minimal --minor  | 'foo 1.5.0', 'bar 2.1.0'  |
 
 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 unlocked, so `foo` can only go to 1.4.4 to maintain
-the dependency to `bar`.
+In case 2, `bar` still moves because it is not a _declared_ dependency in the
+Gemfile, but it is a dependency of `foo` and is therefore free to move if 
+`foo`'s requirement of `bar` changes. If `bar` appeared in the Gemfile, then 
+it would stay put in this case and `foo` would only move to 1.4.4. 
 
 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
@@ -159,14 +184,18 @@ In case 5, both `foo` and `bar` have any minor or major increments removed
 from consideration because of the `-s` strict flag, so the most they can
 move is up to 1.4.4 and 2.0.4.
 
-In case 6, the prefer minimal switch `-p` means they only increment to the
+In case 6, the prefer minimal switch `-n` means they only increment to the
 next available release.
 
-In case 7, the `-p` and `-m` switches allow both to move to just the next
+In case 7, the `-s` strict flag removes any `bar` 2.1 versions from
+consideration, which restricts `foo` to 1.4.4 at latest. `bar` is not unlocked
+and therefore doesn't move.
+
+In case 8, the `-n` and `-m` switches allow both to move to just the next
 available minor version.
 
 
-### Troubleshooting
+## Troubleshooting
 
 First, make sure the current `bundle` command itself runs to completion on its
 own without any problems.
@@ -211,18 +240,24 @@ At the end of all of this though, again, the requirements in the Gemfile
 trump anything else, and the most control you have is by modifying those
 in the Gemfile.
 
+## Breaking Changes from 0.x to 1.0
+
+* Command line options with underscores now uses hyphens instead of 
+  underscores. (Underscore versions will still work, but are undocumented).
+  
+* Some options have been renamed. (Old names will still work, but will be
+  undocumented).
+  
+  * `--minor_preferred` => `--minor`
+  * `--prefer_minimal` => `--minimal` / `-p` => `-n`
+  * `--strict_updates` => `--strict`
+  
+In the "Two Gems" cases documented above, case 2 was _wrong_ (the docs were
+incorrect, there was no bug in the code). Case 2 has been corrected and a
+new similar case has been inserted towards the end of the table. 
 
 ## Development
 
-### Status
-
-0.x versions are subject to breaking changes, there's a fair amount of
-experimenting going on.
-
-We'd love to get real world scenarios where things don't go as planned to help
-flesh out varying details of what many believe a conservative update should
-be.
-
 ### How To
 
 After checking out the repo, run `bin/setup` to install dependencies. Then,

data/lib/bundler/patch/advisory_consolidator.rb

@@ -70,6 +70,7 @@ module Bundler::Patch
   class GemPatch
     include Comparable
 
+    # TODO: requested_version is better name than new_version?
     attr_reader :gem_name, :old_version, :new_version, :patched_versions
 
     def initialize(gem_name:, old_version: nil, new_version: nil, patched_versions: nil)

data/lib/bundler/patch/cli.rb

@@ -7,18 +7,25 @@ module Bundler::Patch
   class CLI
     def self.execute
       opts = Slop.parse! do
-        banner "Bundler Patch Version #{Bundler::Patch::VERSION}\nUsage: bundle patch [options] [gems_to_update]\n\nbundler-patch attempts to update gems conservatively.\n"
-        on '-m', '--minor_preferred', 'Prefer update to the latest minor.release version.'
-        on '-p', '--prefer_minimal', 'Prefer minimal version updates over most recent release (or minor if -m used).'
-        on '-s', '--strict_updates', 'Restrict any gem to be upgraded past most recent release (or minor if -m used).'
+        banner "Bundler Patch Version #{Bundler::Patch::VERSION}\nUsage: bundle patch [options] [gems-to-update]\n\nbundler-patch attempts to update gems conservatively.\n"
+        on '-m', '--minor', 'Prefer update to the latest minor.patch version.'
+        on '-n', '--minimal', 'Prefer minimal version updates over most recent patch (or minor if -m used).'
+        on '-s', '--strict', 'Restrict any gem to be upgraded past most recent patch (or minor if -m used).'
         on '-l', '--list', 'List vulnerable gems and new version target. No updates will be performed.'
-        on '-v', '--vulnerable_gems_only', 'Only update vulnerable gems.'
-        on '-a=', '--advisory_db_path=', 'Optional custom advisory db path. `gems` dir will be appended to this path.'
-        on '-d=', '--ruby_advisory_db_path=', 'Optional path for ruby advisory db. `gems` dir will be appended to this path.'
+        on '-v', '--vulnerable-gems-only', 'Only update vulnerable gems.'
+        on '-a=', '--advisory-db-path=', 'Optional custom advisory db path. `gems` dir will be appended to this path.'
+        on '-d=', '--ruby-advisory-db-path=', 'Optional path for ruby advisory db. `gems` dir will be appended to this path.'
         on '-r', '--ruby', 'Update Ruby version in related files.'
         on '--rubies=', 'Supported Ruby versions. Comma delimited or multiple switches.', as: Array, delimiter: ','
         on '-h', 'Show this help'
         on '--help', 'Show README.md'
+        # will be stripped in help display and normalized to hyphenated options
+        on '--vulnerable_gems_only'
+        on '--advisory_db_path='
+        on '--ruby_advisory_db_path='
+        on '-p', '--prefer_minimal'
+        on '--minor_preferred'
+        on '--strict_updates'
       end
 
       options = opts.to_hash
@@ -31,8 +38,9 @@ module Bundler::Patch
       CLI.new.patch(options)
     end
 
-    def self.show_help(opts)
-      puts opts
+    def self.show_help(slop)
+      slop.options.delete_if { |o| o.long =~ /_/ }
+      puts slop
       exit
     end
 
@@ -48,6 +56,8 @@ module Bundler::Patch
     def patch(options={})
       Bundler.ui = Bundler::UI::Shell.new
 
+      normalize_options(options)
+
       return list(options) if options[:list]
 
       patch_ruby(options[:rubies]) if options[:ruby]
@@ -55,6 +65,17 @@ module Bundler::Patch
       patch_gems(options)
     end
 
+    def normalize_options(options)
+      map = {:prefer_minimal => :minimal, :strict_updates => :strict, :minor_preferred => :minor}
+      {}.tap do |target|
+        options.each_pair do |k, v|
+          new_key = k.to_s.gsub('-', '_').to_sym
+          new_key = map[new_key] || new_key
+          target[new_key] = v
+        end
+      end
+    end
+
     private
 
     def list(options)

data/lib/bundler/patch/conservative_definition.rb

@@ -72,9 +72,9 @@ module Bundler::Patch
       @bundler_def ||= Bundler.definition(@gems_to_update.to_bundler_definition)
       @bundler_def.extend ConservativeDefinition
       @bundler_def.gems_to_update = @gems_to_update
-      @bundler_def.strict = @options[:strict_updates]
-      @bundler_def.minor_preferred = @options[:minor_preferred]
-      @bundler_def.prefer_minimal = @options[:prefer_minimal]
+      @bundler_def.strict = @options[:strict]
+      @bundler_def.minor_preferred = @options[:minor]
+      @bundler_def.prefer_minimal = @options[:minimal]
       fixup_empty_remotes if @gems_to_update.to_bundler_definition === true
       @bundler_def
     end
@@ -105,6 +105,7 @@ module Bundler::Patch
 
     def initialize(gem_patches)
       @gem_patches = Array(gem_patches)
+      STDERR.puts "Unlocked gems: #{unlocking_description}" if ENV['DEBUG_PATCH_RESOLVER']
     end
 
     def to_bundler_definition
@@ -126,5 +127,9 @@ module Bundler::Patch
     def unlocking_gem?(gem_name)
       unlocking_all? || to_gem_names.include?(gem_name)
     end
+
+    def unlocking_description
+      unlocking_all? ? 'ALL' : to_gem_names.sort.join(', ')
+    end
   end
 end

data/lib/bundler/patch/version.rb

@@ -1,5 +1,5 @@
 module Bundler
   module Patch
-    VERSION = '0.10.4'
+    VERSION = '1.0.0.pre.1'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bundler-patch
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 1.0.0.pre.1
 platform: ruby
 authors:
 - chrismo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-24 00:00:00.000000000 Z
+date: 2017-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-advise
@@ -132,7 +132,6 @@ files:
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
-- BUNDLER.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -167,9 +166,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8

data/BUNDLER.md

@@ -1,258 +0,0 @@
-# Conservative Bundle Updates
-
-Starting with 1.13.0.rc.2, a subset of bundler-patch behavior was ported to Bundler itself.
-The plan is to leave it undocumented and unsupported in 1.13 to give it a chance to 
-be used and flush out bugs and iron out some design decisions.
-
-Part of that work before 1.14 (or maybe a later version) will be to properly document
-`bundle update` as well as the [Conservative Updating](http://bundler.io/v1.12/man/bundle-install.1.html#CONSERVATIVE-UPDATING)
-section of `bundle install`, but right now we need a placeholder document showing the new
-stuff so folks know how to use it.
-
-This is largely copy/pasta of the bundler-patch [README](README.md).
-
-## Usage
-
-The default `bundle update` behavior remains untouched. Use of the new `--patch`
-or `--minor` options will invoke the new conservative update behavior.
-
-"Conservative" means it will sort all available versions to prefer the
-latest releases from the current version, then the latest minor releases and
-then the latest major releases.
-
-"Prefer" means that no available versions are removed from consideration, to
-help ensure a suitable dependency graph can be reconciled. This does mean some
-gems cannot be upgraded or may be upgraded to unexpected versions. NOTE: There is
-a `--strict` option which _will_ remove versions from consideration, see below.
-
-Gem requirements as defined in the Gemfile will still define what versions are available.
-The new conservative behavior controls the preference order of those versions.
-
-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 will be "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0,
-2.0.0".
-
-In the same example, if gem 'foo' has a requirement of '~> 1.0', version 2.0.0
-will be removed from consideration as always.
-
-With no gem names provided on the command line, all gems will be unlocked and
-open for updating. 
-
-    $ bundle update --patch 
-
-A list of gem names can be passed to restrict to just those gems.
-
-    $ bundle update --patch foo bar
-
-  * `--patch` option will give preference for release/patch versions, then minor,
-    then major.
-    
-  * `--minor` option will give preference for minor versions over
-    release versions, then major versions.
-
-  * `--major` option will give preference for major versions over
-    minor or release versions. This is the default behavior currently, so this
-    flag is cosmetic for now. Bundler 2.0 will likely make `--patch` the default
-    behavior.
-
-  * `--strict` option will actually remove from consideration
-    versions outside either the current release (or minor version if `--minor`
-    specified). This increases the chances of Bundler being unable to
-    reconcile the dependency graph and in some cases could even raise a 
-    `VersionConflict`.
-
-## Examples
-
-### Single Gem
-
-| Requirements| Locked  | Available                         | Option   | Result |
-|-------------|---------|-----------------------------------|----------|--------|
-| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1, 2.0.0 | --patch  | 1.4.5  |
-| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1, 2.0.0 | --minor  | 1.5.1  |
-| foo         | 1.4.3   | 1.4.4, 1.4.5, 1.5.0, 1.5.1, 2.0.0 | --major  | 2.0.0  |
-
-### Two Gems
-
-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)
-
-| # | 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 unlocked, but because no other gem depends on `bar`
-and `bar` is not a declared dependency in the Gemfile, `bar` is free to move, 
-and so the result is the same as case 1. 
-
-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 1.5.x, 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.
-
-### Shared Dependencies
-
-#### Shared Cannot Move
-
-Given the following gem specifications:
-
-- foo 1.4.3, requires: ~> shared 2.0, ~> bar 2.0
-- foo 1.4.4, requires: ~> shared 2.0, ~> bar 2.0
-- foo 1.4.5, requires: ~> shared 2.1, ~> bar 2.1
-- foo 1.5.0, requires: ~> shared 2.1, ~> bar 2.1
-- qux 1.0.0, requires: ~> shared 2.0.0           
-- bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1
-- shared with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1
-
-Gemfile: 
-
-    gem 'foo'
-    gem 'qux'
-
-Gemfile.lock: 
-
-    bar (2.0.3)
-    foo (1.4.3)
-      bar (~> 2.0)
-      shared (~> 2.0)
-    qux (1.0.0)
-      shared (~> 2.0.0)
-    shared (2.0.3)
-    
-
-| # | Command Line                   | Result                                    |
-|---|--------------------------------|-------------------------------------------|
-| 1 | bundle update --patch foo      | 'foo 1.4.4', 'bar 2.0.3', 'shared 2.0.3'  |
-| 2 | bundle update --patch foo bar  | 'foo 1.4.4', 'bar 2.0.4', 'shared 2.0.3'  |
-| 3 | bundle update --patch          | 'foo 1.4.4', 'bar 2.0.4', 'shared 2.0.4'  |
-
-In case 1, only `foo` moves. When `foo` 1.4.5 is considered in resolution, it 
-would require `shared` 2.1 which isn't allowed because `qux` is incompatible. 
-Resolution backs up to `foo` 1.4.4, and that is allowed by the `qux` constraint
-on `shared` so `foo` moves. `bar` could legally move, but since it is locked 
-and the current version still satisfies the requirement of `~> 2.0` it stays 
-put.
-
-In case 2, everything is the same, but `bar` is also unlocked, so it is also
-allowed to increment to 2.0.4 which still satisfies `~> 2.0`.
-
-In case 3, everything is unlocked, so `shared` can also bump up a patch version.
-
-#### Shared Can Move
-
-_*This is exactly the same setup as "Shared Cannot Move" except for one change:*_
-The `qux` gem has a looser requirement of `shared`: `~> 2.0` instead of `~> 2.0.0`.
-
-Given the following gem specifications:
-
-- foo 1.4.3, requires: ~> shared 2.0, ~> bar 2.0
-- foo 1.4.4, requires: ~> shared 2.0, ~> bar 2.0
-- foo 1.4.5, requires: ~> shared 2.1, ~> bar 2.1
-- foo 1.5.0, requires: ~> shared 2.1, ~> bar 2.1
-- qux 1.0.0, requires: ~> shared 2.0           
-- bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1
-- shared with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1
-
-Gemfile: 
-
-    gem 'foo'
-    gem 'qux'
-
-Gemfile.lock: 
-
-    bar (2.0.3)
-    foo (1.4.3)
-      bar (~> 2.0)
-      shared (~> 2.0)
-    qux (1.0.0)
-      shared (~> 2.0)
-    shared (2.0.3)
-    
-
-| # | Command Line                   | Result                                    |
-|---|--------------------------------|-------------------------------------------|
-| 1 | bundle update --patch foo      | 'foo 1.4.5', 'bar 2.1.1', 'shared 2.1.1'  |
-| 2 | bundle update --patch foo bar  | 'foo 1.4.5', 'bar 2.1.1', 'shared 2.1.1'  |
-| 3 | bundle update --patch          | 'foo 1.4.5', 'bar 2.1.1', 'shared 2.1.1'  |
-
-In all 3 cases, because `foo` 1.4.5 depends on newer versions of `bar` and 
-`shared`, and no requirements from `qux` are restricting those two from moving, 
-then all move as far as allowed here.
- 
-`foo` can only move to 1.4.5 and not 1.5.0 because of the `--patch` flag. 
- 
-As previously demonstrated (see Two Cases) `bar` and `shared` move past the 
-`--patch` restriction because `--strict` is not in play, they are not declared 
-dependencies in the Gemfile and they need to move to satisfy the new `foo` 
-requirement.
-
-### Bundle Install Like Conservative Updating
-
-As detailed in [Bundle Install Docs](http://bundler.io/v1.13/man/bundle-install.1.html#CONSERVATIVE-UPDATING)
-there is a way to prevent shared dependencies from moving after (a) changing 
-a requirement in the Gemfile and (b) using `bundle install`. There's currently
-not an equivalent way to do this with `bundler-patch` or `bundle update` but
-this may change in the future.
-
-### Troubleshooting
-
-First, make sure the current `bundle` command itself runs to completion on its
-own without any problems.
-
-The most frequent problems involve expectations around what
-gems should or shouldn't be upgraded. This can quickly get complicated as even
-a small dependency tree can involve many moving parts, and Bundler works hard
-to find a combination that satisfies all of the dependencies and requirements.
-
-NOTE: the requirements in the Gemfile trump anything else. The most control
-you have is by modifying those in the Gemfile, in some circumstances it may be
-better to pin your versions to what you need instead of trying to diagnose why
-Bundler isn't calculating the versions you expect with a broader requirement.
-If there is an incompatibility, pinning to desired versions can also aide in
-debugging dependency conflicts.
-
-You can get a (very verbose) look into how Bundler's resolution algorithm is
-working by setting the `DEBUG_RESOLVER` environment variable. While it can be
-tricky to dig through, it should explain how it came to the conclusions it
-came to.
-
-In particular, grep for 'Unwinding for conflict' in the debug output to
-isolate some key issues that may be preventing the outcome you expect.
-
-To get additional Bundler debugging output, enable the `DEBUG` env variable.
-This will include all of the details of the downloading the full dependency
-data from remote sources.
-
-At the end of all of this though, again, the requirements in the Gemfile
-trump anything else, and the most control you have is by modifying those
-in the Gemfile.