Add versions documentation.

3 files changed, 18 insertions, 3 deletions

diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index 72afa387e..69a47b211 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -9,7 +9,7 @@ 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 Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`   |
+| **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` |
diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md
index e2257e534..3adf26b87 100644
--- a/docs/Tips-N'-Tricks.md
+++ b/docs/Tips-N'-Tricks.md
@@ -2,8 +2,8 @@
 
 ## Installing previous versions of formulae
 
-The preferred and supported method of installing specific versions of
-formulae is to use formula like e.g. `gcc@6`. 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.