Merge pull request #743 from MikeMcQuaid/version-scheme-cookbook-audit

Add Formula Cookbook entry and audit check for version_scheme

3 files changed, 38 insertions, 14 deletions

diff --git a/Library/Homebrew/cmd/audit.rb b/Library/Homebrew/cmd/audit.rb
index b46f47ab5..f167e457e 100644
--- a/Library/Homebrew/cmd/audit.rb
+++ b/Library/Homebrew/cmd/audit.rb
@@ -209,6 +209,7 @@ class FormulaAuditor
       [/^  version ["'][\S\ ]+["']/,       "version"],
       [/^  (sha1|sha256) ["'][\S\ ]+["']/, "checksum"],
       [/^  revision/,                      "revision"],
+      [/^  version_scheme/,                "version_scheme"],
       [/^  head ["'][\S\ ]+["']/,          "head"],
       [/^  stable do/,                     "stable block"],
       [/^  bottle do/,                     "bottle block"],
@@ -622,22 +623,31 @@ class FormulaAuditor
     end
   end
 
-  def audit_revision
+  def audit_revision_and_version_scheme
     return unless formula.tap # skip formula not from core or any taps
     return unless formula.tap.git? # git log is required
 
     fv = FormulaVersions.new(formula, :max_depth => 10)
-    revision_map = fv.revision_map("origin/master")
-    revisions = revision_map[formula.version]
-    if !revisions.empty?
-      problem "revision should not decrease" if formula.revision < revisions.max
-    elsif formula.revision != 0
+    attributes = [:revision, :version_scheme]
+    attributes_map = fv.version_attributes_map(attributes, "origin/master")
+
+    attributes.each do |attribute|
+      attributes_for_version = attributes_map[attribute][formula.version]
+      if !attributes_for_version.empty?
+        if formula.send(attribute) < attributes_for_version.max
+          problem "#{attribute} should not decrease"
+        end
+      end
+    end
+
+    revision_map = attributes_map[:revision]
+    if formula.revision != 0
       if formula.stable
         if revision_map[formula.stable.version].empty? # check stable spec
-          problem "revision should be removed"
+          problem "'revision #{formula.revision}' should be removed"
         end
       else # head/devel-only formula
-        problem "revision should be removed"
+        problem "'revision #{formula.revision}' should be removed"
       end
     end
   end
@@ -1006,7 +1016,7 @@ class FormulaAuditor
     audit_formula_name
     audit_class
     audit_specs
-    audit_revision
+    audit_revision_and_version_scheme
     audit_desc
     audit_homepage
     audit_bottle_spec
diff --git a/Library/Homebrew/formula_versions.rb b/Library/Homebrew/formula_versions.rb
index 13cb8ac8c..2c5aae8f5 100644
--- a/Library/Homebrew/formula_versions.rb
+++ b/Library/Homebrew/formula_versions.rb
@@ -60,14 +60,22 @@ class FormulaVersions
     map
   end
 
-  def revision_map(branch)
-    map = Hash.new { |h, k| h[k] = [] }
+  def version_attributes_map(attributes, branch)
+    attributes_map = {}
+    return attributes_map if attributes.empty?
+    attributes.each do |attribute|
+      attributes_map[attribute] = Hash.new { |h, k| h[k] = [] }
+    end
+
     rev_list(branch) do |rev|
       formula_at_revision(rev) do |f|
-        map[f.stable.version] << f.revision if f.stable
-        map[f.devel.version] << f.revision if f.devel
+        attributes.each do |attribute|
+          map = attributes_map[attribute]
+          map[f.stable.version] << f.send(attribute) if f.stable
+          map[f.devel.version] << f.send(attribute) if f.devel
+        end
       end
     end
-    map
+    attributes_map
   end
 end
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`):