From 200cc95846867b6f3bb441e6d422dc8ec49385ee Mon Sep 17 00:00:00 2001
From: Markus Reiter <me@reitermark.us>
Date: Fri, 8 Jan 2021 04:57:43 +0100
Subject: [PATCH] Add docs for `livecheck` stanza. (#97486)

---
 doc/cask_language_reference/all_stanzas.md    |  1 +
 doc/cask_language_reference/livecheck.md      | 60 +++++++++++++++++++
 .../stanzas/appcast.md                        |  2 +
 3 files changed, 63 insertions(+)
 create mode 100644 doc/cask_language_reference/livecheck.md

diff --git a/doc/cask_language_reference/all_stanzas.md b/doc/cask_language_reference/all_stanzas.md
index 598864a4b6..80ed7e01a7 100644
--- a/doc/cask_language_reference/all_stanzas.md
+++ b/doc/cask_language_reference/all_stanzas.md
@@ -51,6 +51,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install).
 | `depends_on`           | yes                           | List of dependencies and requirements for this Cask.<br />See [Depends_on Stanza Details](stanzas/depends_on.md) for more information.
 | `conflicts_with`       | yes                           | List of conflicts with this Cask (*not yet functional*).<br />See [Conflicts_with Stanza Details](stanzas/conflicts_with.md) for more information.
 | `caveats`              | yes                           | String or Ruby block providing the user with Cask-specific information at install time.<br />See [Caveats Stanza Details](stanzas/caveats.md) for more information.
+| `livecheck`            | no                            | Ruby block describing how to find updates for this Cask.<br />See [Livecheck Stanza Details](stanzas/livecheck.md) for more information.
 | `preflight`            | yes                           | Ruby block containing preflight install operations (needed only in very rare cases).
 | `postflight`           | yes                           | Ruby block containing postflight install operations.<br />See [Postflight Stanza Details](stanzas/flight.md) for more information.
 | `uninstall_preflight`  | yes                           | Ruby block containing preflight uninstall operations (needed only in very rare cases).
diff --git a/doc/cask_language_reference/livecheck.md b/doc/cask_language_reference/livecheck.md
new file mode 100644
index 0000000000..3c19767d13
--- /dev/null
+++ b/doc/cask_language_reference/livecheck.md
@@ -0,0 +1,60 @@
+# `livecheck`
+
+The `livecheck` stanza is used to automatically fetch the latest version of a cask from changelogs, release notes, appcasts, etc.
+
+Every `livecheck` block must contain a `url`, which can either be a string or a symbol pointing to other URLs in the cask (`:url` or `:homepage`).
+
+Additionally, a `livecheck` should specify which `strategy` should be used to extract the version:
+
+| `strategy`      | Description |
+|-----------------|-----------|
+| `:header_match` | extract version from HTTP headers (e.g. `Location` or `Content-Disposition`) |
+| `:page_match`   | extract version from page contents                                           |
+| `:sparkle`      | extract version from Sparkle appcast contents                                |
+
+Here is a basic example, extracting a simple version from a page:
+
+```ruby
+livecheck do
+  url "https://example.org/my-app/download"
+  strategy :page_match
+  regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+end
+```
+
+If the download URL is present on the homepage, we can use a symbol instead of a string:
+
+```ruby
+livecheck do
+  url :homepage
+  strategy :page_match
+  regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+end
+```
+
+
+The `header_match` strategy will try parsing a version from the filename (in the `Content-Disposition` header) and the final URL (in the `Location` header). If that doesn't work, a `regex` can be specified, e.g.:
+
+```ruby
+strategy :header_match
+regex(/MyApp-(\d+(?:\.\d+)*)\.zip/i)
+```
+
+If the version depends on multiple header fields, a block can be specified, e.g.
+
+```ruby
+strategy :header_match do |headers|
+  v = headers["content-disposition"][/MyApp-(\d+(?:\.\d+)*)\.zip/i, 1]
+  id = headers["location"][%r{/(\d+)/download$}i, 1]
+  "#{v},#{id}"
+end
+```
+
+Similarly, the `:page_match` strategy can also be used for more complex versions by specifying a block:
+
+```ruby
+strategy :page_match do |page|
+  match = page.match(%r{href=.*?/(\d+)/MyApp-(\d+(?:\.\d+)*)\.zip}i)
+  "#{match[2]},#{match[1]}"
+end
+```
diff --git a/doc/cask_language_reference/stanzas/appcast.md b/doc/cask_language_reference/stanzas/appcast.md
index 13c219c41f..7031b0ffff 100644
--- a/doc/cask_language_reference/stanzas/appcast.md
+++ b/doc/cask_language_reference/stanzas/appcast.md
@@ -2,6 +2,8 @@
 
 The value of the `appcast` stanza is a string, holding the URL for an appcast which provides information on future updates.
 
+Note: The [`livecheck` stanza](livecheck.md) should be preferred in most cases, as it allows casks to be updated automatically.
+
 The main casks repo only accepts submissions for stable versions of software (and [documented exceptions](https://github.com/Homebrew/homebrew-cask/blob/master/doc/development/adding_a_cask.md#but-there-is-no-stable-version)), but it still gets pull requests for unstable versions. By checking the submitted `version` against the contents of an appcast, we can better detect these invalid cases.
 
 Example: [`atom.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/atom.rb#L7)