Merge pull request #1767 from MikeMcQuaid/docs-updates

General documentation updates.

8 files changed, 27 insertions, 37 deletions

diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md
index b827403d8..ac65d0802 100644
--- a/docs/Acceptable-Formulae.md
+++ b/docs/Acceptable-Formulae.md
@@ -67,12 +67,8 @@ Formulae in the core repository must have a stable version tagged by
 the upstream project. Tarballs are preferred to git checkouts, and
 tarballs should include the version in the filename whenever possible.
 
-Software that only provides a development/beta, tagged version should be put in
-[homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only).
 We don’t accept software without a tagged version because they regularly break
-due to upstream changes; we can’t provide [bottles](Bottles.md) for them; and
-we don’t have an automatic update mechanism for `head-only` formulae which
-makes them very quickly outdated.
+due to upstream changes and we can’t provide [bottles](Bottles.md) for them.
 
 ### Bindings
 First check that there is not already a binding available via
diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md
index 1d662c158..43b8dfc01 100644
--- a/docs/Custom-GCC-and-cross-compilers.md
+++ b/docs/Custom-GCC-and-cross-compilers.md
@@ -15,7 +15,6 @@ GCC or cross-compiler suite, please link it in here.
 
 * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
 C++11 support on earlier versions.
-* [Homebrew-versions](https://github.com/homebrew/homebrew-versions) provides an
-up to date GCC duplicates e.g. `brew install homebrew/versions/gcc48`
+* Homebrew provides older GCC formulae e.g. `gcc@4.8` and `gcc@6`
 * [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
 toolchain including binutils and gcc.
diff --git a/docs/FAQ.md b/docs/FAQ.md
index b9cbcd225..82efbf454 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -212,23 +212,8 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created
 ```
 
 ### Where was a formula deleted?
-Use `brew log $FORMULA` to find out!
-
-Sometimes formulae are moved to specialized repositories. These are the
-likely candidates:
-
-* [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes)
-* [homebrew/games](https://github.com/Homebrew/homebrew-games)
-* [homebrew/versions](https://github.com/Homebrew/homebrew-versions)
-
-You can use `brew tap` to access these formulae:
-
-```bash
-brew tap homebrew/games
-brew install …
-```
-
-Note that brew search still finds formula in taps.
+Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or
+our analytics identified it was not widely used.
 
 ### Homebrew is a poor name, it is generic, why was it chosen?
 @mxcl was too concerned with the beer theme and didn’t consider that the
diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 6657b9766..69a47b211 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -9,11 +9,11 @@ A formula is a package definition written in Ruby. It can be created with `brew
 | **Keg**        | The installation prefix of a **Formula**                   | `/usr/local/Cellar/foo/0.1`                                     |
 | **opt prefix** | A symlink to the active version of a **Keg**               | `/usr/local/opt/foo `                                           |
 | **Cellar**     | All **Kegs** are installed here                            | `/usr/local/Cellar`                                             |
-| **Tap**        | An optional Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-versions`   |
+| **Tap**        | A Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`   |
 | **Bottle**     | Pre-built **Keg** used instead of building from source     | `qt-4.8.4.mavericks.bottle.tar.gz`                              |
 | **Cask**       | An [extension of homebrew](https://github.com/caskroom/homebrew-cask) to install macOS native apps  | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` |
 | **Brew Bundle**| An [extension of homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies    | `brew 'myservice', restart_service: true` |
- 
+
 ## An Introduction
 
 Homebrew uses Git for downloading updates and contributing to the project.
@@ -33,7 +33,7 @@ Before submitting a new formula make sure your package:
 *   isn't in another official [Homebrew tap](https://github.com/Homebrew)
 *   isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/pulls))
 *   is still supported by upstream (i.e. doesn't require extensive patching)
-*   has a stable, tagged version (i.e. not just a GitHub repository with no versions). See [Interesting-Taps-&-Forks](Interesting-Taps-&-Forks.md) for where pre-release versions belong.
+*   has a stable, tagged version (i.e. not just a GitHub repository with no versions).
 *   passes all `brew audit --new-formula $FORMULA` tests.
 
 Before submitting a new formula make sure you read over our [contribution guidelines](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md).
diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
index a3497abca..ef6091e2c 100644
--- a/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
+++ b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
@@ -4,6 +4,9 @@ The following commands are used by Homebrew contributors to set up a fork of Hom
 
 Depending on the change you want to make, you need to send the pull request to the appropriate one of Homebrew's main repositories. If you want to submit a change to Homebrew core code (the `brew` implementation), you should open the pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open the pull request on [the `homebrew/core` tap](https://github.com/Homebrew/homebrew-core) or another [official tap](https://github.com/Homebrew), based on the formula type.
 
+## Submit a new version of an existing formula
+1. Use `brew bump-formula-pr` to do everything (i.e. forking, committing, pushing) with a single command. Run `brew bump-formula-pr --help` to learn more.
+
 ## Set up your own fork of the Homebrew repository
 
 ### Core `brew` code related pull request
diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md
index d42a97f54..dcb860a23 100644
--- a/docs/Interesting-Taps-&-Forks.md
+++ b/docs/Interesting-Taps-&-Forks.md
@@ -12,16 +12,12 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
 
 *   [homebrew/completions](https://github.com/Homebrew/homebrew-completions): Shell completion formulae.
 
-*   [homebrew/devel-only](https://github.com/Homebrew/homebrew-devel-only): A tap for brews that only have pre-release/development versions.
-
 *   [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes): Need GDB or a newer Tk? System duplicates go here.
 
 *   [homebrew/emacs](https://github.com/Homebrew/homebrew-emacs): A tap for Emacs packages.
 
 *   [homebrew/games](https://github.com/Homebrew/homebrew-games): Game or gaming-emulation related formulae.
 
-*   [homebrew/head-only](https://github.com/Homebrew/homebrew-head-only): A tap for brews that only have unstable, unreleased versions. This tap is **deprecated** and doesn’t accept new formulae.
-
 *   [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.
@@ -32,8 +28,6 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
 
 *   [homebrew/services](https://github.com/Homebrew/homebrew-services): A tool to start Homebrew formulae's plists with `launchctl`.
 
-*   [homebrew/versions](https://github.com/Homebrew/homebrew-versions): Need e.g. older or newer versions of Postgresql? Older versions of GCC?
-
 *   [homebrew/x11](https://github.com/Homebrew/homebrew-x11): Formulae with hard X11 dependencies.
 
 `brew search` looks in these main taps as well as in [homebrew/core](https://github.com/Homebrew/homebrew-core). So don't worry about missing stuff. We will add other taps to the search as they become well maintained and popular.
diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md
index fc532c019..3adf26b87 100644
--- a/docs/Tips-N'-Tricks.md
+++ b/docs/Tips-N'-Tricks.md
@@ -2,10 +2,8 @@
 
 ## Installing previous versions of formulae
 
-The preferred and supported method of installing specific versions of
-formulae is to use the
-[homebrew/versions](https://github.com/Homebrew/homebrew-versions)
-tap.  If the version you’re looking for isn’t available, consider [opening a
+The supported method of installing specific versions of
+some formulae is to see if there is a versions formula like e.g. `gcc@6` available. If the version you’re looking for isn’t available, consider [opening a
 pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)!
 
 ### Installing directly from pull-requests
diff --git a/docs/Versions.md b/docs/Versions.md
new file mode 100644
index 000000000..87bc9f566
--- /dev/null
+++ b/docs/Versions.md
@@ -0,0 +1,15 @@
+# Versions
+Now that [Homebrew/versions](https://github.com/homebrew/homebrew-versions) has been deprecated [Homebrew/core](https://github.com/homebrew/homebrew-core) supports multiple versions of formulae with a new naming format.
+
+In [Homebrew/versions](https://github.com/homebrew/homebrew-versions) the formula for GCC 6 was named `gcc6.rb` and began `class Gcc6 < Formula`. In [Homebrew/core](https://github.com/homebrew/homebrew-core) this same formula is named `gcc@6.rb` and begins `class GccAT6 < Formula`.
+
+## Acceptable Versioned Formulae
+Homebrew's versions are not intended to be used for any old versions you personally require for your project; formulae submitted should be expected to be used by a large number of people and still supported by their upstream projects.
+
+Versioned formulae we include must meet the following standards:
+
+* Versioned formulae should differ in major/minor (not patch) versions from the current stable release. This is because patch versions indicate bug or security updates and we want to ensure you apply security updates.
+* Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`.
+* Versioned formulae should strive to be linked at the same time as their non-versioned counterpart (without patching). If this is not possible, favour either `conflicts_with` or `keg_only` depending on whether users expect to have multiple versions installed at once or not.
+
+You should create your own [tap](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wishes to control the versioning of or those that do not meet the above standards.