sha256 :no_check overrides version <string>

CONTRIBUTING.md

@@ -66,7 +66,7 @@ cask :v1 => 'unity' do
 end
 ```
 
-And here is one for `Firefox.app`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check` (necessary since the checksum will change when a new version is available). This combination of `version :latest` and `sha256 :no_check` is currently the preferred mechanism when an unversioned download URL is available:
+And here is one for `Firefox.app`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check` (necessary since the checksum will change when a new distribution is made available). This combination of `version :latest` and `sha256 :no_check` is currently the preferred mechanism when an unversioned download URL is available:
 
 ```ruby
 cask :v1 => 'firefox' do
@@ -137,7 +137,7 @@ Fill in the following stanzas for your Cask:
 | name               | value       |
 | ------------------ | ----------- |
 | `version`          | application version; give the value `:latest` if an unversioned download is available
-| `sha256`           | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`.  Can be suppressed for unversioned downloads by using the special value `:no_check`. (see also [Checksum Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#checksum-stanza-details))
+| `sha256`           | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`.  Can be suppressed by using the special value `:no_check`. (see also [Checksum Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#checksum-stanza-details))
 | `url`              | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#url-stanza-details))
 | `name`             | the full and proper name defined by the vendor, and any useful alternate names (see also [Name Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#name-stanza-details))
 | `homepage`         | application homepage; used for the `brew cask home` command

doc/CASK_LANGUAGE_REFERENCE.md

@@ -74,7 +74,7 @@ Each of the following stanzas is required for every Cask.
 | name               | multiple occurrences allowed? | value       |
 | ------------------ |------------------------------ | ----------- |
 | `version`          | no                            | application version; give value of `:latest`  if versioned downloads are not offered
-| `sha256`           | no                            | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`.  Can be suppressed for unversioned downloads by using the special value `:no_check`. (see also [Checksum Stanza Details](#checksum-stanza-details))
+| `sha256`           | no                            | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`.  Can be suppressed by using the special value `:no_check`. (see also [Checksum Stanza Details](#checksum-stanza-details))
 | `url`              | no                            | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details](#url-stanza-details))
 | `homepage`         | no                            | application homepage; used for the `brew cask home` command
 | `license`          | no                            | a symbol identifying the license category for the application. (see also [License Stanza Details](#license-stanza-details))
@@ -259,8 +259,23 @@ end
 
 ## Checksum Stanza Details
 
-Casks should no longer use `no_checksum` stanzas.  That form has
-been superseded by `sha256 :no_check`.
+### Calculating the SHA256
+
+The `sha256` value is usually calculated by the command
+
+```bash
+$ shasum -a 256 <file>
+```
+
+### Special Value `:no_check`
+
+The special value `sha256 :no_check` is used to turn off SHA checking
+whenever checksumming is impractical due to the upstream configuration.
+
+`version :latest` requires `sha256 :no_check`, and this pairing is common.
+However, `sha256 :no_check` does not require `version :latest`.
+
+We use a checksum whenever possible.
 
 
 ## URL Stanza Details

lib/cask/audit.rb

@@ -15,7 +15,6 @@ def run!(download = false)
     _check_no_string_version_latest
     _check_checksums
     _check_sha256_no_check_if_latest
-    _check_sha256_if_versioned
     _check_sourceforge_download_url_format
     _check_download(download) if download
     return !(errors? or warnings?)
@@ -53,13 +52,6 @@ def _check_sha256_no_check_if_latest
     end
   end
 
-  def _check_sha256_if_versioned
-    odebug "Verifying a sha256 is present when versioned"
-    if cask.version != :latest and cask.sums == :no_check
-      add_error "you must include a sha256 when version is not :latest"
-    end
-  end
-
   def _check_download(download)
     odebug "Auditing download"
     download.perform

spec/cask/audit_spec.rb

@@ -38,11 +38,6 @@ class CaskVersionLatestWithChecksum < Cask
   sha256 '9203c30951f9aab41ac294bbeb1dcef7bed401ff0b353dcb34d68af32ea51853'
 end
 
-class CaskWithVersionNoChecksum < Cask
-  version '1.2.3'
-  sha256 :no_check
-end
-
 describe Cask::Audit do
   describe "result" do
     it "is 'failed' if there are have been any errors added" do
@@ -89,12 +84,6 @@ class CaskWithVersionNoChecksum < Cask
         audit.run!
         expect(audit.errors).to include(%q{you should use sha256 :no_check when version is :latest})
       end
-
-      it "adds an error if versioned and has no checksum" do
-        audit = Cask::Audit.new(CaskWithVersionNoChecksum.new)
-        audit.run!
-        expect(audit.errors).to include(%q{you must include a sha256 when version is not :latest})
-      end
     end
 
     describe "preferred download URL formats" do