build: generate every generated file with go generate, and check them all with one stale-file step #513

New issue

Open

opened 2026-09-15 22:52:09 +00:00 by hexajon · 0 comments

hexajon commented

2026-09-15 22:52:09 +00:00

Owner

What happens

madtea commits three kinds of generated output, each with its own generator and its own check mode:

Generated file	Generate by hand	Gate check
`docs/reference/*.md`, `internal/mcp/help_generated.go`	`go run ./cmd/madtea-dev docs generate`	`docs generate --verify`
`THIRD-PARTY-LICENSES.md`	`scripts/gen-third-party-licenses.sh`	`gen-third-party-licenses.sh --check`
`go.mod`, `go.sum`	`go mod tidy`	`go mod tidy -diff`

There is no //go:generate line anywhere in the repo. A contributor must know each generator, run each one by hand, and read a separate CONTRIBUTING.md line for each. Every new generator adds a flag, a gate step, and a doc line. The gate only reports stale files; it never tells you the one command that fixes them all, because there is none.

The Go way

From go help generate:

"Go generate is never run automatically by go build, go test, and so on. It must be run explicitly."
Generated files are committed, and their first line matches ^// Code generated .* DO NOT EDIT\.$.
//go:generate lines in the source declare the generators, and go generate ./... runs all of them.

The usual CI check is: run the generators, then git diff --exit-code. The toolchain does the same for modules with go mod tidy -diff.

Ask

//go:generate lines for every generated output: the docs reference and help_generated.go (via madtea-dev docs generate), and THIRD-PARTY-LICENSES.md (via the script). Put them in the package that owns each output, or in one gen.go.
One contributor command: go generate ./... on the feature branch, then commit the output through finish. No generated file changes outside a branch.
One gate step: go generate ./..., then git diff --exit-code, which names every stale file. It replaces docs generate --verify and gen-third-party-licenses.sh --check. The license generator keeps its current order in the gate: serial, before the tests, because it runs go mod download all and restores go.sum.
CI only checks. CI runs the same step and never writes or commits.
Docs: CONTRIBUTING.md says "run go generate ./..." once, in place of the per-generator lines, and docs/contributing/ci.md describes the single step.
Optional: on a dependency-bump branch, the job or bot that makes the bump runs go generate ./... and commits to that same branch. It is still a branch and a PR, never a direct write to main.

Acceptance

go generate ./... on a clean tree changes nothing.
After a change that makes any generated file stale, the gate and CI fail with the names of the stale files, and go generate ./... fixes all of them.
The custom --verify and --check modes are gone from the gate (a generator may keep a check mode for its own tests).
CONTRIBUTING.md has one generate instruction.

## What happens madtea commits three kinds of generated output, each with its own generator and its own check mode: | Generated file | Generate by hand | Gate check | |---|---|---| | `docs/reference/*.md`, `internal/mcp/help_generated.go` | `go run ./cmd/madtea-dev docs generate` | `docs generate --verify` | | `THIRD-PARTY-LICENSES.md` | `scripts/gen-third-party-licenses.sh` | `gen-third-party-licenses.sh --check` | | `go.mod`, `go.sum` | `go mod tidy` | `go mod tidy -diff` | There is no `//go:generate` line anywhere in the repo. A contributor must know each generator, run each one by hand, and read a separate `CONTRIBUTING.md` line for each. Every new generator adds a flag, a gate step, and a doc line. The gate only reports stale files; it never tells you the one command that fixes them all, because there is none. ## The Go way From `go help generate`: - "Go generate is never run automatically by go build, go test, and so on. It must be run explicitly." - Generated files are committed, and their first line matches `^// Code generated .* DO NOT EDIT\.$`. - `//go:generate` lines in the source declare the generators, and `go generate ./...` runs all of them. The usual CI check is: run the generators, then `git diff --exit-code`. The toolchain does the same for modules with `go mod tidy -diff`. ## Ask 1. **`//go:generate` lines** for every generated output: the docs reference and `help_generated.go` (via `madtea-dev docs generate`), and `THIRD-PARTY-LICENSES.md` (via the script). Put them in the package that owns each output, or in one `gen.go`. 2. **One contributor command:** `go generate ./...` on the feature branch, then commit the output through `finish`. No generated file changes outside a branch. 3. **One gate step:** `go generate ./...`, then `git diff --exit-code`, which names every stale file. It replaces `docs generate --verify` and `gen-third-party-licenses.sh --check`. The license generator keeps its current order in the gate: serial, before the tests, because it runs `go mod download all` and restores `go.sum`. 4. **CI only checks.** CI runs the same step and never writes or commits. 5. **Docs:** `CONTRIBUTING.md` says "run `go generate ./...`" once, in place of the per-generator lines, and `docs/contributing/ci.md` describes the single step. 6. **Optional:** on a dependency-bump branch, the job or bot that makes the bump runs `go generate ./...` and commits to that same branch. It is still a branch and a PR, never a direct write to `main`. ## Acceptance - `go generate ./...` on a clean tree changes nothing. - After a change that makes any generated file stale, the gate and CI fail with the names of the stale files, and `go generate ./...` fixes all of them. - The custom `--verify` and `--check` modes are gone from the gate (a generator may keep a check mode for its own tests). - `CONTRIBUTING.md` has one generate instruction.

hexajon added the

enhancement

label

2026-09-15 22:52:09 +00:00

hexajon referenced this issue

2026-09-15 23:09:55 +00:00

Epic: accepted decisions are enforced by checks, not only recorded #518

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#513

No description provided.

Rows
Columns