From 4e21e69109b513534964d47f10adb2d12c4ce93f Mon Sep 17 00:00:00 2001
From: Daniel Young <danyoungmusic93@gmail.com>
Date: Thu, 23 Jul 2026 12:34:45 -0400
Subject: [PATCH] [ci] Restore PR-only formula gate, document why
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reverts the previous commit's premise. test-bot selects formulae by
diffing HEAD against origin/main, so on a push to main the diff is empty
and --only-formulae reports green having tested (none) — verified on two
consecutive pushes, including one that changed tailctl.rb.

Running it on push therefore cannot work. The gate has to be a PR, so
document that formula changes land by PR and record the bump checklist.

Solves: a formula gate that silently tested nothing
Tests: this PR is itself the check — it should build and test tailctl
---
 .github/workflows/tests.yml |  8 +++++---
 README.md                   | 31 ++++++++++++++++++++++++++++---
 2 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 92067e0..04b4938 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -42,12 +42,14 @@ jobs:
       - run: brew test-bot --only-setup
 
       - run: brew test-bot --only-tap-syntax
-      # Formulae land here by direct push, not by PR, so this must run on both
-      # events or the build/test gate never actually fires.
+      # PR-only by necessity: test-bot picks formulae by diffing HEAD against
+      # origin/main, which is empty on a push to main. Formula changes must
+      # therefore land via PR to get built and tested — see README.
       - run: brew test-bot --only-formulae
+        if: github.event_name == 'pull_request'
 
       - name: Upload bottles as artifact
-        if: always()
+        if: always() && github.event_name == 'pull_request'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: bottles_${{ matrix.os }}
diff --git a/README.md b/README.md
index 5922a46..e978fed 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,40 @@
 
 ## How do I install these formulae?
 
-`brew install drycodeworks/tap/<formula>`
+`brew install drycodeworks/tap/tailctl`
 
-Or `brew tap drycodeworks/tap` and then `brew install <formula>`.
+Or `brew tap drycodeworks/tap` and then `brew install tailctl`.
 
 Or, in a `brew bundle` `Brewfile`:
 
 ```ruby
 tap "drycodeworks/tap"
-brew "<formula>"
+brew "tailctl"
+```
+
+## Formulae
+
+- [`tailctl`](https://github.com/DRYCodeWorks/tailctl) — per-identity Tailscale
+  networking for parallel sessions on a single Mac.
+
+## Changing a formula
+
+**Land formula changes via pull request, not a direct push to main.**
+
+`brew test-bot` picks which formulae to build by diffing `HEAD` against
+`origin/main`. On a push to main those are the same commit, so the diff is empty
+and CI reports green having built nothing (`testing_formulae (none)`). Only a PR
+gives it a base to diff against, and only then does CI actually install, test,
+and audit the formula.
+
+Bumping a version:
+
+```bash
+brew livecheck drycodeworks/tap/<formula>     # is there a new release?
+# update url + sha256 (and resources, if dependencies changed)
+brew install --build-from-source drycodeworks/tap/<formula>
+brew test drycodeworks/tap/<formula>
+brew audit --strict --online drycodeworks/tap/<formula>
 ```
 
 ## Documentation