Update docs to reflect revised guidance to check in locks for gems

2 files changed, 20 insertions, 2 deletions

diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn
index c7e38e154f..36144bf4d5 100644
--- a/man/bundle-install.ronn
+++ b/man/bundle-install.ronn
@@ -295,12 +295,20 @@ of a dependency of a gem in your Gemfile(5)) can result in radically
 different gems being needed to satisfy all dependencies.
 
 As a result, you `SHOULD` check your `Gemfile.lock` into version
-control. If you do not, every machine that checks out your
-repository (including your production server) will resolve all
+control, in both applications and gems. If you do not, every machine that
+checks out your repository (including your production server) will resolve all
 dependencies again, which will result in different versions of
 third-party code being used if `any` of the gems in the Gemfile(5)
 or any of their dependencies have been updated.
 
+When Bundler first shipped, the `Gemfile.lock` was gitignored inside gems.
+Over time, however, it became clear that this practice forces the pain of
+broken dependencies onto new contributors, while leaving existing contributors
+potentially unaware of the problem. Since `bundle install` is usually the
+first step towards a contribution, the pain of broken dependencies would
+discourage new contributors from contributing. As a result, we have revised our
+guidance for gem authors to now recommend checking in the lock for gems.
+
 ## CONSERVATIVE UPDATING
 
 When you make a change to the Gemfile(5) and then run `bundle install`,
diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn
index 9baa7f8e3e..d8c03b33b6 100644
--- a/man/gemfile.5.ronn
+++ b/man/gemfile.5.ronn
@@ -504,3 +504,13 @@ bundler uses the following priority order:
      `rubygems.org`
   3. The sources specified via global `source` lines, searching each source in
      your `Gemfile` from last added to first added.
+
+## Should I check my `Gemfile.lock` into version control?
+
+When Bundler first shipped, the `Gemfile.lock` was gitignored inside gems.
+Over time, however, it became clear that this practice forces the pain of
+broken dependencies onto new contributors, while leaving existing contributors
+potentially unaware of the problem. Since `bundle install` is usually the
+first step towards a contribution, the pain of broken dependencies would
+discourage new contributors from contributing. As a result, we have revised our
+guidance for gem authors to now recommend checking in the lock for gems.