Auto merge of #6184 - arbonap:pa-check-in-gemfile-docs, r=indirect

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

Thanks so much for the contribution!
To make reviewing this PR a bit easier, please fill out answers to the following questions.

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

The problem was...
- Bundler stopped gitignoring gem locks. The change was merged in but we need to reflect that change in documentation.
### What was your diagnosis of the problem?

My diagnosis was...
- To add in documentation explaining why Bunder now does _not_ gitignore gem locks.
### What is your fix for the problem, implemented in this PR?

My fix...
- Update the `gemfile.lock` section of `bundle install` man pages as well as the `gemfile` man page.
### Why did you choose this fix out of the possible options?

I chose this fix because...
- This addresses open issue https://github.com/bundler/bundler/issues/5879

(cherry picked from commit 30f7b45e2414eb82e1dcc592a4dd5146438f4a63)

1 files changed, 11 insertions, 2 deletions

diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn
index e57aaca118..4841bc0abe 100644
--- a/man/bundle-install.ronn
+++ b/man/bundle-install.ronn
@@ -290,12 +290,21 @@ 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 included in the `.gitignore`
+file included with generated 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`,