docs(ci): the cross-arch _examples/ build runs locally and on GitHub - #79
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Examples Cross-Arch Build job (
examples-build,.github/workflows/ci.yml)has cross-compiled every
_examples/program forlinux/amd64andlinux/arm64since #70, using the samescripts/example-dirs.shenumerationmake ciuses. Three operator-facing statements still told the reader thatbuild ran only in
make ci:Makefile— the# cicomment and the## cihelp line, i.e. whatmake helpprints: "the cross-arch example build runs only here";AGENTS.md— the "make cionly — the cross-architecture build of every_examples/program…" bullet, which already contradicted AGENTS.md's ownCI-jobs paragraph and
docs/design/quality-loop.md;docs/org-adrs.md— the ADR-0038 entry: "while the cross-arch example buildruns only locally".
Makefile's own comment requires those three to say the same thing; #70 updatedci.yml, AGENTS.md's CI-jobs paragraph, andquality-loop.md, but not these.This corrects all three, adds the job to
docs/design/overview.md's two CI jobenumerations (it was missing from both), and pins the claim in
scripts/check-docs.mjsnext to the existing release-config consistency checkso 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 andmake checkrewrites files with
gofmt -w.make verify(the non-mutating gate,which also runs
go mod tidy -diff) was run instead and is green — seeVerification.
go test -race -short ./...— covered by CI's Race Detection job; no Gosource is touched by this PR.
go.modstill declares no dependencies (stdlib only) — unchangednew
scripts/check-docs.mjscheck is demonstrated failing on each of thefour doc edits reverted individually — see Verification
Docs housekeeping
AGENTS.md,docs/design/overview.md,docs/specs/*updated forbehavior or convention changes (
AGENTS.md,docs/design/overview.md,docs/org-adrs.md)instead
Protected boundaries
N/A — no
.github/workflows/**,.goreleaser.yaml,.svu.yaml, orpolicies/agent-governance.jsontouched.ci.ymlis read by the gate script,never modified.
Verification
node scripts/check-docs.mjsgreen:edits in turn (
git checkout HEAD~1 -- <file>) makes the gate exit 1:make verifygreen:make help'scirow now reads: "…the cross-arch example build is alsorun on GitHub by the Examples Cross-Arch Build job) (core ADR-0038)"
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.