6 files changed, 56 insertions, 5 deletions
diff --git a/brew/README.md b/brew/README.md
index e66f0d2c8..829f40c0e 100644
--- a/brew/README.md
+++ b/brew/README.md
@@ -93,4 +93,10 @@ brew/serve-tarball.sh # ensure running in background; only needed for the local
 brew/test.sh # this is very WIP, but generally the goal is if it exits 0 then the tests are green
 ```
 
+A brew audit of a formula candidate can fail and its possible for it to 'brew install' and tailscale start successfully. A clean brew audit is only required (or strongly recommended) for submission to the Homebrew Core repository.
+
+A "clean" brew doctor on the maintainer's host is not required, but its helpful to ensure no unnecessary problems arise with brew testing downstream. And helps ensure that no quirks of the maintainer's host cause the formula to "works on my box!" but then fail on other's machines. Majority of issues it reports will have no impact, but ideally it should be kept silent and exit 0.
+
+A quirk of brew is that it likes to autoupdate under the hood, in reaction to (and not strictly needed to carry out) the user's express commands. This can cause unexpected delays (especially if bandwidth is your bottleneck) during package maintainer testing workflows. And makes it a challenge to achieve perfectly strict idempotency and deterministic installs. It appears to be a known trade-off call made by the Homebrew tool devs.
+
 TODO(mkramlich): flesh out much further; topics: formula vs bottle, sudo vs not, prefix diffs, local vs public ts tap vs core, testing, submission and bumping
diff --git a/brew/generate-formula.sh b/brew/generate-formula.sh
index ea902f3ad..8db1b8515 100755
--- a/brew/generate-formula.sh
+++ b/brew/generate-formula.sh
@@ -79,6 +79,14 @@ cat <<TEMPLATE4
     (var/"lib/tailscale").mkpath
   end
 
+  def caveats
+    <<~EOS
+      To have launchd start tailscale now and restart at boot:
+        sudo brew services start tailscale
+      NOTE: The caveat message below with 'restart at login' is incorrect, but we can't suppress it. Requires sudo.
+    EOS
+  end
+
   plist_options manual: "sudo tailscaled --socket=#{HOMEBREW_PREFIX}/run/tailscale/tailscaled.sock --state=#{HOMEBREW_PREFIX}/lib/tailscale/tailscaled.state"
 
   def plist
@@ -116,7 +124,8 @@ cat <<TEMPLATE4
   end
 
   test do
-    system bin/"tailscale", "--version"
+    system bin/"tailscale", "version"
+    system bin/"tailscaled", "-version"
     system bin/"tailscale", "netcheck"
   end
 end
diff --git a/brew/tailscale.commit-pin.rb b/brew/tailscale.commit-pin.rb
index db8896ee9..e997dac1e 100644
--- a/brew/tailscale.commit-pin.rb
+++ b/brew/tailscale.commit-pin.rb
@@ -58,6 +58,14 @@ class Tailscale < Formula
     (var/"lib/tailscale").mkpath
   end
 
+  def caveats
+    <<~EOS
+      To have launchd start tailscale now and restart at boot:
+        sudo brew services start tailscale
+      NOTE: The caveat message below with 'restart at login' is incorrect, but we can't suppress it. Requires sudo.
+    EOS
+  end
+
   plist_options manual: "sudo tailscaled --socket=#{HOMEBREW_PREFIX}/run/tailscale/tailscaled.sock --state=#{HOMEBREW_PREFIX}/lib/tailscale/tailscaled.state"
 
   def plist
@@ -95,7 +103,8 @@ class Tailscale < Formula
   end
 
   test do
-    system bin/"tailscale", "--version"
+    system bin/"tailscale", "version"
+    system bin/"tailscaled", "-version"
     system bin/"tailscale", "netcheck"
   end
 end
diff --git a/brew/tailscale.rb b/brew/tailscale.rb
index db8896ee9..e997dac1e 100644
--- a/brew/tailscale.rb
+++ b/brew/tailscale.rb
@@ -58,6 +58,14 @@ class Tailscale < Formula
     (var/"lib/tailscale").mkpath
   end
 
+  def caveats
+    <<~EOS
+      To have launchd start tailscale now and restart at boot:
+        sudo brew services start tailscale
+      NOTE: The caveat message below with 'restart at login' is incorrect, but we can't suppress it. Requires sudo.
+    EOS
+  end
+
   plist_options manual: "sudo tailscaled --socket=#{HOMEBREW_PREFIX}/run/tailscale/tailscaled.sock --state=#{HOMEBREW_PREFIX}/lib/tailscale/tailscaled.state"
 
   def plist
@@ -95,7 +103,8 @@ class Tailscale < Formula
   end
 
   test do
-    system bin/"tailscale", "--version"
+    system bin/"tailscale", "version"
+    system bin/"tailscaled", "-version"
     system bin/"tailscale", "netcheck"
   end
 end
diff --git a/brew/tailscale.tb-github.rb b/brew/tailscale.tb-github.rb
index 7a9fa0d0e..fb136dc67 100644
--- a/brew/tailscale.tb-github.rb
+++ b/brew/tailscale.tb-github.rb
@@ -57,6 +57,14 @@ class Tailscale < Formula
     (var/"lib/tailscale").mkpath
   end
 
+  def caveats
+    <<~EOS
+      To have launchd start tailscale now and restart at boot:
+        sudo brew services start tailscale
+      NOTE: The caveat message below with 'restart at login' is incorrect, but we can't suppress it. Requires sudo.
+    EOS
+  end
+
   plist_options manual: "sudo tailscaled --socket=#{HOMEBREW_PREFIX}/run/tailscale/tailscaled.sock --state=#{HOMEBREW_PREFIX}/lib/tailscale/tailscaled.state"
 
   def plist
@@ -94,7 +102,8 @@ class Tailscale < Formula
   end
 
   test do
-    system bin/"tailscale", "--version"
+    system bin/"tailscale", "version"
+    system bin/"tailscaled", "-version"
     system bin/"tailscale", "netcheck"
   end
 end
diff --git a/brew/tailscale.tb-local.rb b/brew/tailscale.tb-local.rb
index f57c990f8..499e7b0b3 100644
--- a/brew/tailscale.tb-local.rb
+++ b/brew/tailscale.tb-local.rb
@@ -57,6 +57,14 @@ class Tailscale < Formula
     (var/"lib/tailscale").mkpath
   end
 
+  def caveats
+    <<~EOS
+      To have launchd start tailscale now and restart at boot:
+        sudo brew services start tailscale
+      NOTE: The caveat message below with 'restart at login' is incorrect, but we can't suppress it. Requires sudo.
+    EOS
+  end
+
   plist_options manual: "sudo tailscaled --socket=#{HOMEBREW_PREFIX}/run/tailscale/tailscaled.sock --state=#{HOMEBREW_PREFIX}/lib/tailscale/tailscaled.state"
 
   def plist
@@ -94,7 +102,8 @@ class Tailscale < Formula
   end
 
   test do
-    system bin/"tailscale", "--version"
+    system bin/"tailscale", "version"
+    system bin/"tailscaled", "-version"
     system bin/"tailscale", "netcheck"
   end
 end