Skip to content

docs(ci): the cross-arch _examples/ build runs locally and on GitHub - #79

Merged
bketelsen merged 1 commit into
mainfrom
docs/cross-arch-build-scope
Aug 30, 2026
Merged

docs(ci): the cross-arch _examples/ build runs locally and on GitHub#79
bketelsen merged 1 commit into
mainfrom
docs/cross-arch-build-scope

Conversation

@bketelsen

Copy link
Copy Markdown
Contributor

Summary

The Examples Cross-Arch Build job (examples-build, .github/workflows/ci.yml)
has cross-compiled every _examples/ program for linux/amd64 and
linux/arm64 since #70, using the same scripts/example-dirs.sh enumeration
make ci uses. Three operator-facing statements still told the reader that
build ran only in make ci:

  • Makefile — the # ci comment and the ## ci help line, i.e. what
    make help prints: "the cross-arch example build runs only here";
  • AGENTS.md — the "make ci only — the cross-architecture build of every
    _examples/ program…"
    bullet, which already contradicted AGENTS.md's own
    CI-jobs paragraph and docs/design/quality-loop.md;
  • docs/org-adrs.md — the ADR-0038 entry: "while the cross-arch example build
    runs only locally"
    .

Makefile's own comment requires those three to say the same thing; #70 updated
ci.yml, AGENTS.md's CI-jobs paragraph, and quality-loop.md, but not these.
This corrects all three, adds the job to docs/design/overview.md's two CI job
enumerations (it was missing from both), and pins the claim in
scripts/check-docs.mjs next to the existing release-config consistency check
so the local-only wording cannot come back while the job exists.

No workflow, Makefile recipe, or Go source behavior changes.

Checks

  • make check — not run: this is a docs-only change and make check
    rewrites files with gofmt -w. make verify (the non-mutating gate,
    which also runs go mod tidy -diff) was run instead and is green — see
    Verification.
  • go test -race -short ./... — covered by CI's Race Detection job; no Go
    source is touched by this PR.
  • go.mod still declares no dependencies (stdlib only) — unchanged
  • New or changed behavior has focused tests, including failure paths: the
    new scripts/check-docs.mjs check is demonstrated failing on each of the
    four doc edits reverted individually — see Verification

Docs housekeeping

  • AGENTS.md, docs/design/overview.md, docs/specs/* updated for
    behavior or convention changes (AGENTS.md, docs/design/overview.md,
    docs/org-adrs.md)
  • Conformance aliases (ADR-0001) untouched — canonical targets edited
    instead

Protected boundaries

N/A — no .github/workflows/**, .goreleaser.yaml, .svu.yaml, or
policies/agent-governance.json touched. ci.yml is read by the gate script,
never modified.

Verification

  • node scripts/check-docs.mjs green:
    ok   docs_index_coverage: 1.000 (required 1)
    ok   link_integrity: 1.000 (required 1)
    ok   symlink_resolution: 1.000 (required 1)
    checked: 12 docs, 154 links, 9 symlinks
    
  • The new gate actually pins the claim. Reverting each of the four doc
    edits in turn (git checkout HEAD~1 -- <file>) makes the gate exit 1:
    ### revert Makefile
    FAIL cross-arch: Makefile calls the cross-arch _examples/ build local-only ("runs only here") while .github/workflows/ci.yml runs it in the examples-build job
    ### revert AGENTS.md
    FAIL cross-arch: AGENTS.md calls the cross-arch _examples/ build local-only ("`make ci` only") while .github/workflows/ci.yml runs it in the examples-build job
    ### revert docs/org-adrs.md
    FAIL cross-arch: docs/org-adrs.md calls the cross-arch _examples/ build local-only ("runs only locally") while .github/workflows/ci.yml runs it in the examples-build job
    ### revert docs/design/overview.md
    FAIL cross-arch: docs/design/overview.md does not name the Examples Cross-Arch Build job that .github/workflows/ci.yml defines
    
    (each run exited 1; the tree was restored and the gate returned to exit 0)
  • make verify green:
    ==> verify: go.mod is tidy
    go mod tidy -diff
    ==> verify: gofmt
    ==> verify: golangci-lint 2.13.1 (built with go >= 1.26.7)
    0 issues.
    0 issues.
    go vet ./...
    go vet ./_examples/deploy ./_examples/fileprocess ./_examples/healthcheck ./_examples/migration
    ==> verify: tests
    go test ./...
    ok  	github.com/frostyard/std/reporter	0.002s
    ok  	github.com/frostyard/std/tests/e2e	3.033s
    
  • make help's ci row now reads: "…the cross-arch example build is also
    run on GitHub by the Examples Cross-Arch Build job) (core ADR-0038)"
  • Checked against the
    PR review rubric

Risk classification

Low. Documentation and one added docs-gate assertion. No Go source, no
Makefile recipe body, no workflow, no threshold, and no gate weakened — the
gate only gains a check.

The Examples Cross-Arch Build job (`examples-build`) has cross-compiled every
_examples/ program for linux/amd64 and linux/arm64 since #70, off the same
scripts/example-dirs.sh enumeration `make ci` uses. Three operator-facing
statements still said that build ran only in `make ci`:

- the Makefile `# ci` comment and its `## ci` help line (what `make help`
  prints);
- AGENTS.md's "**`make ci` only**" bullet, which already contradicted
  AGENTS.md's own CI-jobs paragraph and docs/design/quality-loop.md;
- docs/org-adrs.md's ADR-0038 entry ("runs only locally").

Correct all three, add the job to docs/design/overview.md's two CI job
enumerations, and pin the claim in scripts/check-docs.mjs alongside the
existing release-config consistency check, so the docs gate fails if the
local-only wording comes back while the job exists.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@bketelsen
bketelsen marked this pull request as ready for review August 30, 2026 02:28
@bketelsen
bketelsen added this pull request to the merge queue Aug 30, 2026
Merged via the queue into main with commit dae9f4a Aug 30, 2026
8 checks passed
@bketelsen
bketelsen deleted the docs/cross-arch-build-scope branch August 30, 2026 02:31
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.

1 participant