Documentation
¶
Overview ¶
Command apigate is the Go API-compatibility gate for forge/pkg: the packages every generated project imports. Run it with `go run ./internal/apigate`; it is CI plumbing, no part of the forge binary.
apigate [-base REV] [-dir .] [-pr N] [-body-file FILE] [-label L]...
It compares the exported API under pkg/ at the merge base with the working tree, using golang.org/x/exp/apidiff, and fails on an incompatible change unless the change is DECLARED and ships its remedy:
- declared: the PR carries the `api-break` label, or a line `API-BREAK: [codemod=<name>] [playbook=migrations/<vX.Y.Z>]` appears in the PR body or a commit body;
- shipped: the same diff adds a `forge fix <name>` codemod (a non-test file in internal/codemod registering that name) or touches a migration playbook (internal/templates/project/skills/forge/migrations/<version>/).
forge is pre-1.0 and owes no compatibility; this gate does not forbid a break, it makes the breaking PR carry the cost of its consumers' migration instead of the next pinner. See dev-docs/api-breaks.md.
WHERE THE DECLARATION COMES FROM. With -pr, the label list and body are read live through `gh api` (GH_TOKEN, GITHUB_REPOSITORY), not from the workflow event: a label added after the run started, then "Re-run failed jobs", is seen. Locally, pass -label and -body-file instead.
Source Files