Skip to content

Add cut-release skill covering the Homebrew tap step - #323

Open
vpetersson-bot wants to merge 3 commits into
masterfrom
docs/cut-release-skill
Open

vpetersson-bot wants to merge 3 commits into
masterfrom
docs/cut-release-skill

Conversation

@vpetersson-bot

@vpetersson-bot vpetersson-bot commented Sep 13, 2026 •

Copy link
Copy Markdown

What does this PR do?

Adds a cut-release agent skill and makes syncing the Homebrew tap an explicit, required release step.

The tap (Screenly/homebrew-screenly-cli) had drifted a full release behind (pinned to v26.8.0 after v26.9.0 shipped). That is now fixed by homebrew-screenly-cli#18, and the tap matches v26.9.0; this PR is about keeping it from happening again. The reason it drifts is structural: it is a separate repo, nothing in release.yml points at it, and skipping it fails silently — brew install screenly-cli just keeps serving the previous version. The README had it as a one-line trailing bullet.

Changes:

  • .claude/skills/cut-release/SKILL.md — full release runbook, following the same format as the cut-release / anthias-release skills in Screenly/Anthias. Covers the tap bump as step 4 of the release (not a follow-up), plus standalone drift checks for both Homebrew and nixpkgs.
  • README.md — step 4 is now a short required step (bump tag: in the tap's formula, then verify) that links to the skill for the details, so the two don't drift apart.

The skill also records the details that are easy to get wrong:

  • CalVer month is not zero-padded (26.8.0, not 26.08.0) — Cargo.toml is parsed as strict SemVer.
  • Four files carry the version, and they disagree on the v prefix: Cargo.toml is bare, action.yml and Dockerfile are v-prefixed, Cargo.lock is regenerated via cargo build.
  • mcpb/manifest.json must not be bumped — its 0.0.0 is a deliberate placeholder the release workflow overwrites from the tag.
  • flake.nix must not be bumped either — it reads version from Cargo.toml via builtins.fromTOML, so it follows automatically.

The v prefix, and what else it touches

The companion tap PR (homebrew-screenly-cli#18) drops the v from the formula version by deleting the version field rather than rewriting it — Homebrew derives the version from the tag and strips the v on its own, which leaves tag: as the only line a release touches. The runbook here is updated to match; an earlier revision of this branch said to keep the v, which was backwards.

Worth knowing, since it explains why: Homebrew tokenises a leading v as a StringToken that sorts below any NumericToken, so v-prefixed versions compare as older than every bare one, and FormulaAudit/Version rejects the prefix outright.

This also surfaced a second, larger drift. nixpkgs (nix-shell -p screenly-cli, advertised in our README) is a different package from our in-repo flake, and it is still on 1.2.1 — four releases back, predating the CalVer switch entirely. Its nix-update-script bot last filed a PR in July 2026 (1.2.0 -> 1.2.1) and has filed nothing for 1.2.2, 26.8.0 or 26.9.0. That is not fixed here — it is someone else's repo — but the skill now includes a spot-check so it gets noticed at release time.

GitHub issue or Phabricator ticket number?

SIRI-98

How has this been tested?

Docs-only — no code paths touched.

Version facts were verified against the repo rather than written from memory: the four version-carrying files were found by grepping for the current version, the mcpb/manifest.json placeholder behaviour was read out of release.yml, and flake.nix was read to confirm it derives from Cargo.toml.

The Homebrew claims were verified by running the real Version class from Homebrew 7.0.1 rather than asserting them: token breakdown, 26.9.0 > v26.8.0 (so the transition upgrades cleanly), and Version.detect on the git URL + tag returning "26.9.0" (so the version field is safely removable). The gh drift-check commands in the skill were run as written.

docs.yml is unaffected — its docs-help-md job diffs generated CLI help against docs/CommandLineHelp.md and does not look at README prose. It passed on the previous push.

Checklist before merging

  • If have added tests. — n/a, docs only
  • Is this a new feature? If yes, please write one phrase about this update. — no, documentation
  • I've attached relevant screenshots (if relevant). — n/a

🤖 Generated with Claude Code

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot AI review requested due to automatic review settings September 13, 2026 18:50

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

vpetersson-bot and others added 2 commits September 15, 2026 08:05
The Homebrew tap lives in a separate repo (Screenly/homebrew-screenly-cli)
with no automation linking it to our release workflow, so when it is
skipped nothing fails — `brew install screenly-cli` just keeps serving the
previous version. It had drifted a full release behind (v26.8.0 while we
shipped v26.9.0).

Add a `cut-release` skill that documents the whole release path and treats
the tap bump as a required release step rather than a follow-up, plus a
standalone drift check. Also record the details that are easy to get wrong:
the non-zero-padded CalVer month, the four files to bump and which spell
the version with a `v`, and the mcpb/manifest.json placeholder that must
not be touched.

Expand the README release section to point at the skill and spell out the
formula fields.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>
Follow-up to the tap change: the formula no longer carries an explicit
`version` field at all, so the runbook's "bump both fields" instruction was
wrong in both directions. Homebrew derives the version from the tag and
strips the leading `v`, which leaves `tag:` as the only line a release
touches and makes the version underivable from anything but the tag.

The previous text also told the reader to keep the `v` prefix as an
established convention. That was backwards: Homebrew tokenises a leading
`v` as a StringToken sorting below any NumericToken, so `v`-prefixed
versions compare as older than every bare one, and the FormulaAudit/Version
cop rejects the prefix outright. Record that, and that the switch is
one-way.

Also correct the distribution-channel notes. nixpkgs is a separate package
from our in-repo flake.nix, and while it self-updates via nix-update-script
the bot has gone quiet: nixpkgs is still on 1.2.1 while we ship 26.9.0, so
`nix-shell -p screenly-cli` serves a pre-CalVer build. Add a spot-check for
it, and note that flake.nix needs no action because it reads the version
from Cargo.toml.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Active release-check issues remain: the documented commands are not macOS-portable and may resolve an older release instead of the newly pushed tag.

3 open issues

Review effort: Lite

Comment thread .claude/skills/cut-release/SKILL.md Outdated

```bash
# what the tap currently pins vs. what we just shipped
gh release view --repo Screenly/cli --json tagName -q .tagName

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. The step now runs gh release view vYY.M.MICRO, so an unpublished release fails instead of resolving to the previous one. Fixed in 6eb5e1a.

Comment thread .claude/skills/cut-release/SKILL.md Resolved
Comment thread README.md Outdated
```bash
gh release view --repo Screenly/cli --json tagName -q .tagName
gh api repos/Screenly/homebrew-screenly-cli/contents/Formula/screenly-cli.rb \
--jq .content | base64 -d | grep 'tag:'

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block is gone from the README; it now links to the skill, which uses base64 --decode. Fixed in 6eb5e1a.

@salmanfarisvp salmanfarisvp left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vpetersson-bot thanks, this runbook is useful. I checked its claims against the repo and nixpkgs, and they hold: the mcpb/manifest.json placeholder plus the jq injection in release.yml, flake.nix reading Cargo.toml through fromTOML, the target list, attestation and Docker tags, the four version-carrying files and their v prefixes, and nixpkgs still on 1.2.1. The nixpkgs finding alone makes this worth merging.

A few things to fix before it goes in:

  1. The same content is in two places. The README's new step 4 repeats most of the skill (the no-version-field explanation, the sha256 note, the verify commands). The copies will drift apart. Could the README keep a short step 4 (bump tag: in the tap's Formula/screenly-cli.rb, then verify) and link to the skill for the details?
  2. The PR description is out of date. It says the tap is "a full release behind." That was fixed by homebrew-screenly-cli#18, and the tap now matches v26.9.0. Please update it so reviewers aren't misled.
  3. SKILL.md, step 3: "CI is not run-owned — kick it off and check back; don't block on it" reads as agent-internal jargon. Suggest "The workflow takes a while; check back on it rather than waiting."
  4. SKILL.md, step 0: "the release after 26.8.2 is 26.9.0, not 26.8.3" only holds when the month has changed. Suggest "a new month resets MICRO to 0 (e.g. after 26.8.2, the first September release is 26.9.0)."

Nothing here blocks the content itself. Happy to approve once these are addressed.

Point the README's Homebrew step at the skill instead of duplicating it,
view the release by its tag, use the portable base64 --decode, and
reword the MICRO reset and the CI wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings November 12, 2026 11:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error: Your billing is not configured or you have Copilot licenses from multiple standalone organizations or enterprises. To use premium requests, select a billing entity via the GitHub site, under Settings > Copilot > Features.

@vpetersson-bot

Copy link
Copy Markdown
Author

@salmanfarisvp thanks for checking the claims against the repo and nixpkgs. All four points are addressed in 6eb5e1a:

  1. The README's step 4 is now short: bump tag: in the tap's Formula/screenly-cli.rb, verify, and see the runbook for details. The explanation and verify commands live only in the skill.
  2. The description now says the tap was fixed by homebrew-screenly-cli#18 and matches v26.9.0, so this PR is about keeping it from drifting again.
  3. Step 3 now reads "The workflow takes a while; check back on it rather than waiting."
  4. Step 0 now uses your wording: "a new month resets MICRO to 0 (e.g. after 26.8.2, the first September release is 26.9.0)."

I also took Copilot's points: the tap step now looks up the release by its tag, and the decode uses base64 --decode.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants