Merge branch 'master' into audit_line_rubocop_part_4_rebase_attempt_1

10 files changed, 54 insertions, 61 deletions

diff --git a/docs/Analytics.md b/docs/Analytics.md
index 15fa6fc93..18dc7bfa6 100644
--- a/docs/Analytics.md
+++ b/docs/Analytics.md
@@ -37,7 +37,9 @@ As far as we can tell it would be impossible for Google to match the randomly ge
 Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS.
 
 ## Who?
-Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access.
+Homebrew's detailed analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access.
+
+Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/).
 
 ## How?
 The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 23f53d54c..9d76bf4ab 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -26,6 +26,8 @@ To allow that formulae to update again:
 
     brew unpin <formula>
 
+Note that pinned, outdated formulae that are depended on by another formula will be upgraded when required as we do not allow formulae to be built against non-latest versions.
+
 ## How do I uninstall old versions of a formula?
 By default, Homebrew does not uninstall old versions of a formula, so
 over time you will accumulate old versions. To remove them, simply use:
@@ -66,13 +68,12 @@ Be careful as this is a destructive operation.
 Which is usually: `~/Library/Caches/Homebrew`
 
 ## My Mac `.app`s don’t find `/usr/local/bin` utilities!
-GUI apps on macOS don’t have `/usr/local/bin` in their `PATH` by default.
-If you’re on Mountain Lion, you can fix this by running
-`launchctl setenv PATH "/usr/local/bin:$PATH"`. [More details
-here](https://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x/5444960#5444960),
-including how to set this across reboots. If you’re pre-Mountain Lion,
-[here’s an official
-alternative](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
+GUI apps on macOS don’t have `/usr/local/bin` in their `PATH` by
+default.  If you’re on Mountain Lion or later, you can fix this by
+running `sudo launchctl config user path "/usr/local/bin:$PATH"` and
+then rebooting, as documented in `man launchctl`. Note that this sets
+the launchctl PATH for _all users_. For earlier versions of macOS, see
+[this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
 
 ## How do I contribute to Homebrew?
 Read [CONTRIBUTING.md](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md).
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index e60afe071..0266d39e5 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -693,7 +693,7 @@ Note that [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula
 
 ### File level operations
 
-You can use the file utilities provided by Ruby's [`FileUtils`](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them.
+You can use the file utilities provided by Ruby's [`FileUtils`](https://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them.
 
 When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use
 
diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md
index 692e5c617..8b263cb38 100644
--- a/docs/Homebrew-and-Python.md
+++ b/docs/Homebrew-and-Python.md
@@ -24,13 +24,13 @@ The Python formulae install [pip](http://www.pip-installer.org) (as `pip2` or `p
 Setuptools can be updated via pip, without having to re-brew Python:
 
 ```sh
-pip install --upgrade setuptools
+python2 -m pip --upgrade setuptools
 ```
 
 Similarly, pip can be used to upgrade itself via:
 
 ```sh
-pip install --upgrade pip
+python2 -m pip install --upgrade pip
 ```
 
 ### Note on `pip install --user`
@@ -39,7 +39,7 @@ The normal `pip install --user` is disabled for brewed Python. This is because o
 A possible workaround (which puts executable scripts in `~/Library/Python/<X>.<Y>/bin`) is:
 
 ```sh
-pip install --user --install-option="--prefix=" <package-name>
+python2 -m pip install --user --install-option="--prefix=" <package-name>
 ```
 
 ## `site-packages` and the `PYTHONPATH`
@@ -86,7 +86,7 @@ CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <pa
 Activate the virtualenv *after* you've brewed, or brew in a fresh Terminal window.
 Homebrew will still install Python modules into Homebrew's `site-packages` and *not* into the virtual environment's site-package.
 
-Virtualenv has a switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
+Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
 
 ## Why is Homebrew's Python being installed as a dependency?
 Formulae that depend on the special `:python` target are bottled against the Homebrew Python and require it to be installed. You can avoid installing Homebrew's Python by building these formulae with `--build-from-source`.
diff --git a/docs/Installation.md b/docs/Installation.md
index e36ed3efa..9f091d2e5 100644
--- a/docs/Installation.md
+++ b/docs/Installation.md
@@ -47,7 +47,7 @@ PowerPC and Tiger branches from other users in the fork network. See
 [Interesting Taps and Forks](Interesting-Taps-and-Forks.md).
 
 <a name="2"><sup>2</sup></a> 10.10 or higher is recommended. 10.5–10.9 are
-supported on a best-effort basis. For 10.4 and 10.5, see
+supported on a best-effort basis. For 10.4 see
 [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
 
 <a name="3"><sup>3</sup></a> Most formulae require a compiler. A handful
diff --git a/docs/Interesting-Taps-and-Forks.md b/docs/Interesting-Taps-and-Forks.md
index 6b70fadec..5e3fc19d2 100644
--- a/docs/Interesting-Taps-and-Forks.md
+++ b/docs/Interesting-Taps-and-Forks.md
@@ -5,11 +5,9 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
 
 ## Main taps
 
-*   [homebrew/apache](https://github.com/Homebrew/homebrew-apache): A tap for Apache modules, extending macOS's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats.
+*   [homebrew/nginx](https://github.com/Homebrew/homebrew-nginx): A tap for NGINX modules, intended for its `nginx-full` formula which includes more module options.
 
-*   [homebrew/nginx](https://github.com/Homebrew/homebrew-nginx): Feature rich Nginx tap for modules.
-
-*   [homebrew/php](https://github.com/Homebrew/homebrew-php): Repository for php-related formulae.
+*   [homebrew/php](https://github.com/Homebrew/homebrew-php): Repository for PHP-related formulae.
 
 *   [homebrew/science](https://github.com/Homebrew/homebrew-science): A collection of scientific libraries and tools.
 
@@ -21,8 +19,6 @@ You can be added as a maintainer for one of the Homebrew organization taps and a
 
 *   [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually.
 
-*   [besport/ocaml](https://github.com/besport/homebrew-ocaml): A tap for Ocaml libraries, though with caveats, it requires you install its customized ocaml formula. Perhaps a template for more work.
-
 *   [osx-cross/avr](https://github.com/osx-cross/homebrew-avr): GNU AVR toolchain (Libc, compilers and other tools for Atmel MCUs, useful for Arduino hackers and AVR programmers).
 
 *   [petere/postgresql](https://github.com/petere/homebrew-postgresql): Allows installing multiple PostgreSQL versions in parallel.
@@ -31,6 +27,10 @@ You can be added as a maintainer for one of the Homebrew organization taps and a
 
 *   [dunn/emacs](https://github.com/dunn/homebrew-emacs): A tap for Emacs packages.
 
+*   [sidaf/pentest](https://github.com/sidaf/homebrew-pentest): Tools for penetration testing.
+
+*   [osrf/simulation](https://github.com/osrf/homebrew-simulation): Tools for robotics simulation.
+
 ## Interesting forks
 
 *   [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version
diff --git a/docs/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md
index 84ba662b4..146718aec 100644
--- a/docs/Kickstarter-Supporters.md
+++ b/docs/Kickstarter-Supporters.md
@@ -379,7 +379,7 @@ These wonderful people supported our Kickstarter by giving us £10 or more:
 * [Andrew Brown](http://pvalu.es)
 * [Bethany Sumner](http://www.bethanysumner.com/)
 * [Orta](http://orta.io)
-* [Michał Gołębiowski](https://github.com/mgol)
+* [Michał Gołębiowski-Owczarek](https://github.com/mgol)
 * [Adam C. Foltzer](http://www.acfoltzer.net/)
 * [Steve Hiemstra](https://www.speg.com)
 * [Anton Sipos](http://www.softwarefuturism.com)
diff --git a/docs/Manpage.md b/docs/Manpage.md
index 49f6bb5ae..f92991147 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -77,7 +77,7 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     a bug report, you will likely be asked for this information if you do not
     provide it.
 
-  * `deps` [`--1`] [`-n`] [`--union`] [`--full-name`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] `formulae`:
+  * `deps` [`--1`] [`-n`] [`--union`] [`--full-name`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] [`--include-requirements`] `formulae`:
     Show dependencies for `formulae`. When given multiple formula arguments,
     show the intersection of dependencies for `formulae`.
 
@@ -98,15 +98,22 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     `formulae`. To include the `:build` type dependencies, pass `--include-build`.
     Similarly, pass `--include-optional` to include `:optional` dependencies.
     To skip `:recommended` type dependencies, pass `--skip-recommended`.
+    To include requirements in addition to dependencies, pass `--include-requirements`.
 
-  * `deps` `--tree` [`filters`] (`formulae`|`--installed`):
+  * `deps` `--tree` [`--1`] [`filters`] [`--annotate`] (`formulae`|`--installed`):
     Show dependencies as a tree. When given multiple formula arguments, output
     individual trees for every formula.
 
+    If `--1` is passed, only one level of children is displayed.
+
     If `--installed` is passed, output a tree for every installed formula.
 
     The `filters` placeholder is any combination of options `--include-build`,
-    `--include-optional`, and `--skip-recommended` as documented above.
+    `--include-optional`, `--skip-recommended`, and `--include-requirements` as
+    documented above.
+
+    If `--annotate` is passed, the build, optional, and recommended dependencies
+    are marked as such in the output.
 
   * `deps` [`filters`] (`--installed`|`--all`):
     Show dependencies for installed or all available formulae. Every line of
@@ -364,7 +371,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
 
   * `pin` `formulae`:
     Pin the specified `formulae`, preventing them from being upgraded when
-    issuing the `brew upgrade` command. See also `unpin`.
+    issuing the `brew upgrade `formulae`` command (but can still be upgraded
+    as dependencies for other formulae). See also `unpin`.
 
   * `postinstall` `formula`:
     Rerun the post-install steps for `formula`.
@@ -529,8 +537,8 @@ With `--verbose` or `-v`, many commands print extra debugging information. Note
     source. This is useful for creating patches for the software.
 
   * `unpin` `formulae`:
-    Unpin `formulae`, allowing them to be upgraded by `brew upgrade`. See also
-    `pin`.
+    Unpin `formulae`, allowing them to be upgraded by `brew upgrade `formulae``.
+    See also `pin`.
 
   * `untap` `tap`:
     Remove a tapped repository.
diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md
index 232ccb1be..4fe19bdb8 100644
--- a/docs/Prose-Style-Guidelines.md
+++ b/docs/Prose-Style-Guidelines.md
@@ -16,7 +16,7 @@ Homebrew's audience includes users with a wide range of education and experience
 
 We strive for "correct" but not "fancy" usage. Think newspaper article, not academic paper.
 
-This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like [The Economist's Style Guide](http://www.economist.com/styleguide/introduction) or [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
+This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like [The Economist's Style Guide](https://www.economist.com/styleguide/introduction) or [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
 
 The intent of this document is to help authors make decisions about clarity, style, and consistency. It is not to help settle arguments about who knows English better. Don't use this document to be a jerk.
 
diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md
index 5b9d6ced6..129f5ba5e 100644
--- a/docs/Python-for-Formula-Authors.md
+++ b/docs/Python-for-Formula-Authors.md
@@ -10,33 +10,7 @@ Bindings are a special case of libraries that allow Python code to interact with
 
 Homebrew is happy to accept applications that are built in Python, whether the apps are available from PyPI or not. Homebrew generally won't accept libraries that can be installed correctly with `pip install foo`. Bindings may be installed for packages that provide them, especially if equivalent functionality isn't available through pip.
 
-## Running `setup.py`
-
-Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns arguments for invoking `setup.py`. Your formula should use this instead of invoking `setup.py` explicitly. The syntax is:
-
-```ruby
-system "python", *Language::Python.setup_install_args(prefix)
-```
-
-where `prefix` is the destination prefix (usually `libexec` or `prefix`).
-
-## Python module dependencies
-
-In general, applications should unconditionally bundle all of their dependencies and libraries and should install any unsatisfied dependencies; these strategies are discussed in depth in the following sections.
-
-In the rare instance that this proves impractical, you can specify a Python module as an external dependency using this syntax:
-
-```ruby
-depends_on "numpy" => :python
-```
-
-Or if the import name is different from the module name:
-
-```ruby
-depends_on "MacFSEvents" => [:python, "fsevents"]
-```
-
-If you submit a formula with this syntax to core, you may be asked to rewrite it as a `Requirement`.
+Applications should unconditionally bundle all of their Python-language dependencies and libraries and should install any unsatisfied dependencies; these strategies are discussed in depth in the following sections.
 
 ## Applications
 
@@ -147,9 +121,9 @@ in case you need to do different things for different resources.
 
 ## Bindings
 
-To add an option to a formula to build Python bindings, use `depends_on :python => :recommended` and install the bindings conditionally on `build.with? "python"` in your `install` method.
+Build bindings with system Python by default (don't add an option) and they should be usable with any binary-compatible Python. If that isn't the case, it's an upstream bug; [here's some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
 
-Python bindings should be optional because if the formula is bottled, any `:recommended` or mandatory dependencies on `:python` are always resolved by installing the Homebrew `python` formula, which will upset users that prefer to use the system Python. This is because we cannot generally create a binary package that works against both versions of Python.
+To add bindings for Python 3, please add `depends_on :python3 => :optional` and make the bindings conditional on `build.with?("python3")`.
 
 ### Dependencies
 
@@ -179,9 +153,7 @@ Sometimes we have to `inreplace` a `Makefile` to use our prefix for the Python b
 
 ### Python declarations
 
-Libraries **should** declare a dependency on `:python` or `:python3` as appropriate, which will respectively cause the formula to use the first python or python3 discovered in `PATH` at install time. If a library supports both Python 2.x and Python 3.x, the `:python` dependency **should** be `:recommended` (i.e. built by default) and the `:python3` dependency should be `:optional`. Python 2.x libraries **must** function when they are installed against either the system Python or Homebrew Python.
-
-Formulae that declare a dependency on `:python` will always be bottled against Homebrew's python, since we cannot in general build binary packages that can be imported from both Pythons. Users can add `--build-from-source` after `brew install` to compile against whichever python is in `PATH`.
+Python 2 libraries do not need a `depends_on :python` declaration; they will be built with system Python, but should still be usable with any other Python 2.7. If this is not the case, it is an upstream bug; [here is some advice for resolving it](http://blog.tim-smith.us/2015/09/python-extension-modules-os-x/). Libraries built for Python 3 should include `depends_on :python3`, which will bottle against Homebrew's python3, and use the first python3 discovered in `PATH` at build time when installing from source with `brew install --build-from-source`. If a library supports both Python 2.x and Python 3.x, the `:python3` dependency should be `:optional`. Python 2.x libraries must function when they are installed against either the system Python or Homebrew Python.
 
 ### Installing
 
@@ -191,7 +163,7 @@ Most formulae presently just install to `prefix`.
 
 ### Dependencies
 
-The dependencies of libraries must be installed so that they are importable. The principle of minimum surprise suggests that installing a Homebrew library should not alter the other libraries in a user's `sys.path`. The best way to achieve this is to only install dependencies if they are not already installed. To minimize the potential for linking conflicts, dependencies should be installed to `libexec/"vendor"` and added to `sys.path` by writing a second .pth file (named like "homebrew-foo-dependencies.pth") to the `prefix` site-packages.
+The dependencies of libraries must be installed so that they are importable. To minimize the potential for linking conflicts, dependencies should be installed to `libexec/"vendor"` and added to `sys.path` by writing a second .pth file (named like "homebrew-foo-dependencies.pth") to the `prefix` site-packages.
 
 The [matplotlib](https://github.com/Homebrew/homebrew-science/blob/master/matplotlib.rb) formula in [homebrew/science](https://github.com/Homebrew/homebrew-science) deploys this strategy.
 
@@ -209,6 +181,16 @@ Distutils and pip use a "flat" installation hierarchy that installs modules as i
 
 Distribute (not to be confused with distutils) is an obsolete fork of setuptools. Distlib is a package maintained outside the standard library which is used by pip for some low-level packaging operations and is not relevant to most `setup.py` users.
 
+### Running `setup.py`
+
+In the event that a formula needs to interact with `setup.py` instead of calling `pip`, Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns useful arguments for invoking `setup.py`. Your formula should use this instead of invoking `setup.py` explicitly. The syntax is:
+
+```ruby
+system "python", *Language::Python.setup_install_args(prefix)
+```
+
+where `prefix` is the destination prefix (usually `libexec` or `prefix`).
+
 ### What is `--single-version-externally-managed`?
 
 `--single-version-externally-managed` ("SVEM") is a setuptools-only [argument to `setup.py install`](https://setuptools.readthedocs.io/en/latest/setuptools.html?#install-run-easy-install-or-old-style-installation). The primary effect of SVEM is to use distutils to perform the install instead of using setuptools' `easy_install`.