From f45b347c44316aaeaea75bb0b5e86213d5e54ddd Mon Sep 17 00:00:00 2001 From: Rian Stockbower Date: Sat, 18 Apr 2026 06:00:13 -0400 Subject: [PATCH 1/2] docs(ci): document workflow buckets and history Groups the 11 workflows into four buckets (CI, auto-release, release, packaging publish, packaging validation) with triggers and intent. Captures the non-obvious history: PR #224 removing the pull_request trigger from packaging test workflows, PR #100 simplifying chocolatey packaging per reviewer feedback, and the GoReleaser tag-rename dance. Closes #252 --- .github/workflows/CLAUDE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .github/workflows/CLAUDE.md diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md new file mode 100644 index 00000000..b693f7ed --- /dev/null +++ b/.github/workflows/CLAUDE.md @@ -0,0 +1,24 @@ +# GitHub Workflows + +Guidance for the 11 workflows in this directory. The root `CLAUDE.md` has the canonical release pipeline details — this file is a map and a source of intent. + +## Buckets + +| Bucket | Files | Trigger | Purpose | +|---|---|---|---| +| CI | `ci.yml` | `push: main`, `pull_request` | Build/test/lint with `dorny/paths-filter` so each tool only runs when its paths (or `shared/`) change. | +| Auto-release | `auto-release-{cfl,jtk}.yml` | `push: main` | Dual-gate tag creation: path gate (Go code only) + commit gate (`feat:`/`fix:`). Creates `{tool}-v{base}.{run}` tags that trigger the release workflow. | +| Release | `release-{cfl,jtk}.yml` | Tag push (`cfl-v*`, `jtk-v*`) | GoReleaser matrix build (darwin/linux/windows × amd64/arm64), GitHub release, Homebrew cask push. Uses the tag-rename trick (see Pitfalls). | +| Packaging publish | `chocolatey-publish-{cfl,jtk}.yml`, `winget-publish-{cfl,jtk}.yml` | `workflow_dispatch` only | Publish to Chocolatey / submit to winget-pkgs. Called manually after a release; depends on release artifacts existing at the expected tag. | +| Packaging validation | `test-chocolatey.yml`, `test-winget.yml` | `push: main` with path filter on `tools/*/packaging/{chocolatey,winget}/**` | Post-merge dry-run validation (nuspec XML, PowerShell syntax, `choco pack`, winget manifest schema). These files aren't covered by `go test` or lint, so this is the only gate on them. | + +## History + +The packaging test workflows originally fired on `pull_request` (since Jan 2026, PR #11), spinning up `windows-latest` on every PR that touched packaging files. Issue #223 / PR #224 (Apr 2026) stripped that trigger — validation now runs only on `push: main`. PR #100 simplified the Chocolatey packaging itself (removed the custom uninstall script and `.ignore` file) per reviewer feedback from the Chocolatey community maintainer. The release workflow's tag-rename dance is a GoReleaser-Free constraint from the monorepo split — GoReleaser needs a semver tag (`v1.0.150`) but the project ships tool-prefixed tags (`cfl-v1.0.150`), so a temporary semver tag is created, consumed, then renamed. + +## Pitfalls + +- **Don't re-add `pull_request` to `test-chocolatey.yml` / `test-winget.yml`.** That undoes PR #224 and burns `windows-latest` runners on every packaging-touching PR. +- **New packaging integrations must account for the tag rename.** GoReleaser runs *before* the tag is renamed from `v1.0.150` to `{tool}-v1.0.150`. Any download URLs generated by GoReleaser must use `url.template` to pin the final tool-prefixed tag, otherwise they reference the deleted temporary tag and 404. See `homebrew_casks` in `.goreleaser-{tool}.yml`. +- **`jira-ticket-cli.rb` is auto-generated from `jtk.rb`** via `sed` in `release-jtk.yml` because GoReleaser Free doesn't support `alternative_names` for casks. +- **Publish workflows are manual.** They don't fire automatically after a release — run them via `gh workflow run` once the release assets are in place. From 3d16d2942e66bf7648da41bc9e6dd25495376b36 Mon Sep 17 00:00:00 2001 From: Rian Stockbower Date: Sat, 18 Apr 2026 06:01:16 -0400 Subject: [PATCH 2/2] docs(ci): correct bucket count in intro (five, not four) --- .github/workflows/CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md index b693f7ed..552f9296 100644 --- a/.github/workflows/CLAUDE.md +++ b/.github/workflows/CLAUDE.md @@ -1,6 +1,6 @@ # GitHub Workflows -Guidance for the 11 workflows in this directory. The root `CLAUDE.md` has the canonical release pipeline details — this file is a map and a source of intent. +Guidance for the 11 workflows in this directory, grouped into five buckets. The root `CLAUDE.md` has the canonical release pipeline details — this file is a map and a source of intent. ## Buckets