From d12b3452bea3eb825d1bc4b9aa83ef29d1efa753 Mon Sep 17 00:00:00 2001 From: Patricia Arbona Date: Wed, 22 Nov 2017 17:11:19 -0500 Subject: [PATCH 1/2] Update docs to reflect revised guidance to check in locks for gems --- man/bundle-install.ronn | 12 ++++++++++-- man/gemfile.5.ronn | 10 ++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn index c7e38e154fa..36144bf4d52 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 9baa7f8e3e7..d8c03b33b66 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. From da6e69224705406698d01cff54bdd9ca18278a4c Mon Sep 17 00:00:00 2001 From: Andre Arko Date: Mon, 12 Feb 2018 17:35:33 -0800 Subject: [PATCH 2/2] Tweak language, remove lock info from Gemfile doc. After reviewing, I think the question and answer is a bad fit for the `gemfile` man page. It does seem like a good fit for the FAQ page on the Bundler documentation site, though, and I'll add it over there. --- man/bundle-install.ronn | 15 ++++++++------- man/gemfile.5.ronn | 10 ---------- 2 files changed, 8 insertions(+), 17 deletions(-) diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn index 36144bf4d52..3945371cce0 100644 --- a/man/bundle-install.ronn +++ b/man/bundle-install.ronn @@ -301,13 +301,14 @@ 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. +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 diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn index d8c03b33b66..9baa7f8e3e7 100644 --- a/man/gemfile.5.ronn +++ b/man/gemfile.5.ronn @@ -504,13 +504,3 @@ 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.