Auto merge of #6605 - forestgagnon:refine-gemfile-source-warning, r=segiddins

add warning to docs for explicit source gotcha

See https://github.com/bundler/bundler/issues/6280 for more context.

This PR adds a warning to the Gemfile documentation to more clearly indicate that specifying an explicit source on a per-gem or block basis also makes that scoped source a global source. Also adds a recommendation that users ensure that all gems in the Gemfile are using explicit sources whenever they introduce any explicit source blocks or source directives on individual gems.

If the root cause cannot be fixed until v2, I think this gotcha should be documented in all existing bundler versions which have this behavior, which as far as I can tell is all versions supporting explicit sources via blocks/per-gem directives. I believe it merits a warning because the behavior is non-intuitive, and represents a potential security issue if it is not understood and avoided. I don't know how backporting for documentation is performed, so I'm making this PR against master for now. Please let me know if I need to do anything else.

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

Unclear behavior when mixing global sources with source blocks, as outlined in https://github.com/bundler/bundler/issues/6280 . No documentation was present that described this behavior.

### What was your diagnosis of the problem?

Having docs would have been helpful!

### What is your fix for the problem, implemented in this PR?

Add documentation

### Why did you choose this fix out of the possible options?

It was suggested that I make a PR to add documentation here: https://github.com/bundler/bundler/issues/6280#issuecomment-400535496

## To Reproduce
```ruby
source 'https://code.stripe.com/'

source 'https://rubygems.org' do
  gem 'fattr'
end

gem 'mime-types'
```
results in this warning on v1.16.2, telling me that it preferred https://rubygems.org for the `mime-types` gem, which is counterintuitive when looking at the Gemfile.

```
Warning: the gem 'mime-types' was found in multiple sources.
Installed from: https://rubygems.org/
Also found in:
  * https://code.stripe.com/
You should add a source requirement to restrict this gem to your preferred source.
For example:
    gem 'mime-types', :source => 'https://rubygems.org/'
Then uninstall the gem 'mime-types' (or delete all bundled gems) and then install again.
```

Here is a Dockerfile that reproduces the issue when built, for source blocks:

```Dockerfile
FROM ruby:2.5.1-alpine
WORKDIR /test

RUN echo $'\n\
  source "https://code.stripe.com/" \n\
  source "https://rubygems.org" do \n\
    gem "fattr" \n\
  end \n\
  gem "mime-types" \n\
  ' >> ./Gemfile

RUN bundle install --verbose
# the source ambiguity warning doesn't show up on the initial install for some reason
RUN rm -rf /usr/local/bundle/**/*
RUN bundle install
RUN cat Gemfile
```

Here is another Dockerfile that reproduces the issue when built, for a source directive on an individual `gem` function call:

```Dockerfile
FROM ruby:2.5.1-alpine
WORKDIR /test

RUN echo $'\n\
  source "https://code.stripe.com/" \n\
  gem "fattr", source: "https://rubygems.org" \n\
  gem "mime-types" \n\
  ' >> ./Gemfile

RUN bundle install --verbose
# the source ambiguity warning doesn't show up on the initial install for some reason
RUN rm -rf /usr/local/bundle/**/*
RUN bundle install
RUN cat Gemfile
```

(cherry picked from commit d6e19e5b20bc561219650dd2b35808294600c798)

1 files changed, 13 insertions, 0 deletions

diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn
index 5c7ba23b29..4354bcd622 100644
--- a/man/gemfile.5.ronn
+++ b/man/gemfile.5.ronn
@@ -251,6 +251,12 @@ Selecting a specific source repository this way also suppresses the ambiguous
 gem warning described above in
 [GLOBAL SOURCES (#source)](#GLOBAL-SOURCES).
 
+Using the `:source` option for an individual gem will also make that source
+available as a possible global source for any other gems which do not specify
+explicit sources. Thus, when adding gems with explicit sources, it is
+recommended that you also ensure all other gems in the Gemfile are using
+explicit sources.
+
 ### GIT
 
 If necessary, you can specify that a gem is located at a particular
@@ -453,6 +459,13 @@ In the case of the `git` block form, the `:ref`, `:branch`, `:tag`,
 and `:submodules` options may be passed to the `git` method, and
 all gems in the block will inherit those options.
 
+The presence of a `source` block in a Gemfile also makes that source
+available as a possible global source for any other gems which do not specify
+explicit sources. Thus, when defining source blocks, it is
+recommended that you also ensure all other gems in the Gemfile are using
+explicit sources, either via source blocks or `:source` directives on
+individual gems.
+
 ## INSTALL_IF
 
 The `install_if` method allows gems to be installed based on a proc or lambda.