Formula-Cookbook: add version_scheme documentation.

1 files changed, 6 insertions, 0 deletions

diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md
index ab51d431e..1772fbd4f 100644
--- a/share/doc/homebrew/Formula-Cookbook.md
+++ b/share/doc/homebrew/Formula-Cookbook.md
@@ -193,6 +193,12 @@ Where a dependent of a formula fails against a new version of that dependency it
 
 [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method)s are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users aren’t left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96).
 
+## Version Scheme Changes
+
+Sometimes formulae have version schemes that change such that a direct comparison between two versions no longer produces the correct result. For example, a project might be version `13` and then decide to become `1.0.0`. As `13` is translated to `13.0.0` by our versioning system by default this requires intervention.
+
+Where a version scheme of a formula fails to recognise a new version as newer it must receive a [`version_scheme`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version_scheme%3D-class_method). An example of this can be seen [here](https://github.com/Homebrew/homebrew-core/pull/4006).
+
 ## Double-check for dependencies
 
 When you already have a lot of formulae installed, it's easy to miss a common dependency. You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`):