From 47eb06e66ab3d0fc5ef6e37cfdac069b518e71e0 Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Wed, 7 Oct 2026 06:42:42 +0000 Subject: [PATCH] docs(bazel): make bazel test the primary build and test path (ga-96smfk.23) Bazel is beads' build and test system: bazel.yml's lanes gate every PR, and nogo (lint + vet), gofmt and the repository guards exist only as Bazel targets. The docs, the Makefile and the hooks now say so. Makefile: `make test` runs bazel.yml's test lane (`bazel test //... --config=ci`), `make check` adds the testing.Short policy and the `make ci-pr-lint` nogo gate, and `make check-docs` runs the docsync and doc-freshness Bazel targets before the pinned-release CLI flag check. BAZEL_FLAGS passes --config=fork-cache or --config=remote-exec through. The plain-Go recipes stay as explicit twins: test-go, check-go, check-docs-go. No workflow called the primary names, and TestWorkflowsNameTheirTestEngine keeps it that way. Hooks: pre-push runs scripts/pre-push-suite.sh for branch pushes whose commits change Go or Bazel inputs: the test lane with --config=remote-exec when some rc names an executor, else --config=fork-cache. Without bazel, or with BD_PREPUSH_SUITE=go, it runs make test-go under a banner saying that is not what CI gates on. Docs: AGENTS.md, CONTRIBUTING.md, engdocs/TESTING.md (a per-lane command table and the fork-cache/remote-exec setup), README, RELEASING, the PR template and the .bazelrc header. Bazelisk is a required prerequisite; go test is an inner-loop convenience CI does not enforce. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) --- .bazelrc | 13 +- .githooks/pre-push | 40 ++++++- .github/PULL_REQUEST_TEMPLATE.md | 2 +- AGENTS.md | 49 +++++--- CONTRIBUTING.md | 52 ++++++-- Makefile | 57 +++++++-- README.md | 2 +- RELEASING.md | 2 +- engdocs/TESTING.md | 102 +++++++++++++--- examples/formulas/primitives/README.md | 2 +- scripts/BUILD.bazel | 2 + scripts/README.md | 2 +- scripts/makefile_bazel_primary_test.go | 135 +++++++++++++++++++++ scripts/pre-push-suite.sh | 140 ++++++++++++++++++++++ scripts/pre_push_suite_test.go | 157 +++++++++++++++++++++++++ 15 files changed, 689 insertions(+), 68 deletions(-) create mode 100644 scripts/makefile_bazel_primary_test.go create mode 100755 scripts/pre-push-suite.sh create mode 100644 scripts/pre_push_suite_test.go diff --git a/.bazelrc b/.bazelrc index 4de47b6c1..497eacc70 100644 --- a/.bazelrc +++ b/.bazelrc @@ -1,6 +1,13 @@ -# Bazel configuration for beads (side-by-side with the Go toolchain; `go build` -# and `go test` are unaffected). Bzlmod only; Bazel version is pinned in -# .bazelversion. +# Bazel configuration for beads. Bazel is beads' build and test system: CI +# gates on the `bazel test` lanes in .github/workflows/bazel.yml, and +# `make test`/`make check` run the same commands (engdocs/TESTING.md +# "Building and Testing"). Plain `go build`/`go test` still work as an +# inner-loop convenience but are not what CI enforces. Where actions run is +# per machine, never committed here: contributors read the anonymous, +# read-only cache with --config=fork-cache (defined below); maintainers with +# an rbe-west client certificate execute remotely with --config=remote-exec. +# Make either the default with a `build --config=...` line in the gitignored +# .bazelrc.local. Bzlmod only; Bazel version is pinned in .bazelversion. common --enable_bzlmod common --color=no # C/C++ (and so cgo, -race and the Go stdlib) builds only with MODULE.bazel's diff --git a/.githooks/pre-push b/.githooks/pre-push index 992d7ece3..fc57efb0b 100755 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -1,8 +1,10 @@ #!/usr/bin/env bash -# Pre-push hook: when pushing a release tag (refs/tags/v*), refuse the push if -# version constants disagree. This stops a release from being tagged/published -# with drifted versions (the failure mode that left main red after the 1.0.5 -# release) before it ever reaches CI. +# Pre-push hook: run the Bazel test suite for branch pushes that change Go or +# Bazel inputs (scripts/pre-push-suite.sh), and when pushing a release tag +# (refs/tags/v*), refuse the push if version constants disagree. The version +# check stops a release from being tagged/published with drifted versions (the +# failure mode that left main red after the 1.0.5 release) before it ever +# reaches CI. # # Installed via: git config core.hooksPath .githooks # See also: make install (sets hooksPath automatically) @@ -55,6 +57,36 @@ if [ "$pushing_version_tag" -eq 1 ]; then fi fi +# The push-time test suite (scripts/pre-push-suite.sh): bazel.yml's test lane, +# `bazel test //... --config=ci`, for branch pushes whose new commits change +# Go or Bazel inputs. A tag push, a deletion, or a docs-only push skips it. +# BD_PREPUSH_SUITE=go runs plain go test instead, under a banner. +zero_sha=0000000000000000000000000000000000000000 +suite_needed=0 +while read -r local_ref local_sha _remote_ref remote_sha; do + case "$local_ref" in + refs/heads/*) ;; + *) continue ;; + esac + if [ "$local_sha" = "$zero_sha" ] || ! git cat-file -e "$local_sha^{commit}" 2>/dev/null; then + continue + fi + base="$remote_sha" + if [ "$base" = "$zero_sha" ] || ! git cat-file -e "$base^{commit}" 2>/dev/null; then + # A new remote branch: compare against main's merge-base. + base="$(git merge-base "$local_sha" origin/main 2>/dev/null || true)" + fi + if [ -z "$base" ] || git diff --name-only "$base" "$local_sha" -- \ + '*.go' 'go.mod' 'go.sum' '*.bazel' '*.bzl' '.bazelrc' '.bazelversion' 'MODULE.bazel.lock' | grep -q .; then + suite_needed=1 + fi +done <<< "$push_refs" + +if [ "$suite_needed" -eq 1 ]; then + repo_root="$(git rev-parse --show-toplevel)" + "$repo_root/scripts/pre-push-suite.sh" > .bazelrc.local -# Run tests (uses correct build tags automatically) +# Run the test suite CI gates on (bazel test //... --config=ci) make test -# Build and install locally to ~/.local/bin +# Build and install bd to ~/.local/bin (also enables the git hooks) make install ``` -Optional: if you use Bazel, opt in to the project's anonymous, read-only -build cache by adding `build --config=fork-cache` to your gitignored -`.bazelrc.local` (or pass `--config=fork-cache` per command). Results CI -already computed become cache hits, and nothing you build is uploaded. It is -off by default. +### Building and Testing + +Bazel is the gate: `.github/workflows/bazel.yml` runs every pull request's +tests as `bazel test` lanes, and nogo (lint + vet), gofmt and the repository +guards exist only as Bazel targets. The make targets run the same commands: + +| Command | Runs | +|---|---| +| `make test` | `bazel test //... --config=ci`: the test lane (unit tests, nogo, gofmt, repository guards) | +| `make check` | the testing.Short policy, `make ci-pr-lint` and `make test` | +| `make ci-pr-lint` | nogo natively plus the windows/amd64 and darwin/arm64 passes | +| `make check-docs` | the Bazel docsync and doc-freshness tests, then the CLI flag check | +| `bazel test //... --config=integration` | the integration lane; [engdocs/TESTING.md](engdocs/TESTING.md) lists every other lane's command | + +Where actions run is your choice, set in the gitignored `.bazelrc.local` (or +per command with `make test BAZEL_FLAGS=--config=...`): + +- `--config=fork-cache` (contributors): reads the anonymous cache, runs misses + on your machine, uploads nothing. +- `--config=remote-exec` (maintainers with an rbe-west client certificate): + executes remotely; the executor and TLS lines stay in your `user.bazelrc` or + `.bazelrc.local`. + +`go test` (`./scripts/test.sh`, or `make test-go` / `make check-go` / +`make check-docs-go`) still works as an inner-loop convenience, but CI does not +enforce it and it skips nogo, gofmt and the guards. Finish with `make test`. ## Project Structure @@ -199,7 +224,8 @@ For test commands, test design, and PR-readiness gates, see the canonical - Follow the proportional validation budget in [engdocs/TESTING.md](engdocs/TESTING.md): docs-only changes use docs checks; - Go changes use focused and affected-package tests plus one final `make test`. + Go changes use focused and affected-package tests plus one final `make test` + (the Bazel test lane). - If you hit a test failure unrelated to your change, don't silently skip it -- check `.test-skip` and file an issue if it's not already tracked (see [engdocs/TESTING.md](engdocs/TESTING.md#failures-skips-and-review)). diff --git a/Makefile b/Makefile index 9797f1555..e9e2a4202 100644 --- a/Makefile +++ b/Makefile @@ -45,6 +45,7 @@ endif .PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen githooks-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short .PHONY: lint lint-changed vet +.PHONY: check check-go test-go check-docs-go .PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-complexity ci-complexity-diff ci-complexity-check ci-package-mcp ci-package-npm .PHONY: api-gen api-check .PHONY: bazel-sync bazel-sync-check @@ -52,6 +53,23 @@ endif # Default target all: build +# Build and test engine. Bazel is what CI gates on: .github/workflows/bazel.yml +# runs `bazel test` lanes on rbe-west, and nogo (lint + vet), formatting and +# the repository guards are Bazel targets there. The primary targets (test, +# check, check-docs) run the same `bazel test` commands as those lanes, so a +# local run shares CI's action keys and its remote cache (engdocs/TESTING.md +# "Building and testing"). Each keeps a plain go twin under an explicit -go +# name (test-go, check-go, check-docs-go) for offline work and hosts Bazel does +# not serve; that twin is an inner-loop convenience, not what CI enforces. +# GitHub Actions jobs that still run Go-native suites call the -go names. +BAZEL ?= bazel +# Extra flags for every `bazel test` below: --config=fork-cache (contributors: +# the anonymous read-only cache) or --config=remote-exec (maintainers with an +# rbe-west client certificate). Hosts whose ~/.bazelrc names the executor need +# neither. Better: put `build --config=...` in the gitignored .bazelrc.local. +BAZEL_FLAGS ?= +BAZEL_TEST = $(BAZEL) test $(BAZEL_FLAGS) + BUILD_DIR := . BD_BUILD_OUTPUT := $(BUILD_DIR)/bd$(if $(filter Windows_NT,$(OS)),.exe) GIT_BUILD := $(shell git rev-parse --short HEAD) @@ -174,11 +192,27 @@ doctor-build: echo " CGO_ENABLED=1 go build -tags gms_pure_go ./cmd/bd" ;; \ esac -# Run all tests (skips known broken tests listed in .test-skip) +# bazel.yml's test lane (`bazel test //... --config=ci`): every untagged +# go_test with PR Core's selection (race, -short, skips), plus nogo lint/vet, +# formatting and the repository guards. The other lanes' commands are in +# engdocs/TESTING.md "Building and testing". test: + $(BAZEL_TEST) //... --config=ci + +# Plain go test (skips known broken tests listed in .test-skip): an inner-loop +# convenience without Bazel; CI does not run it. +test-go: @echo "Running tests..." @TEST_COVER=1 ./scripts/test.sh +# Fast quality gates: the testing.Short policy, the full nogo lint gate +# (native plus the windows/darwin passes) and `make test`. +check: check-testing-short ci-pr-lint test + +# The same gates without Bazel where they have a Go form: gofmt and go test. +# nogo has no go twin, so this is a convenience CI does not enforce. +check-go: fmt-check check-testing-short test-go + # Run the opt-in ICU regex path test suite (no skip list). # This is a local developer workflow for intentionally exercising the leftover # ICU path; it is not part of normal validation. @@ -421,8 +455,15 @@ fmt: fmt-check: @./scripts/ci/fmt-check.sh -# Validate documentation references against actual CLI flags +# Docs checks: docsync and doc freshness as bazel.yml's test lane runs them, +# then the CLI flag check, which validates against bd built from the release in +# docs/cli-docs.pin (so it stays a script, like pr.yml's check-doc-flags job). check-docs: + $(BAZEL_TEST) //test/docsync:docsync_test //scripts/repochecks:doc_freshness_test --config=ci + @./scripts/check-doc-flags.sh + +# The same docs checks with plain go test and a go-built bd. +check-docs-go: @echo "Building bd for docs checks..." @CGO_ENABLED=0 go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o "$(BUILD_DIR)/bd" ./cmd/bd @./scripts/check-doc-flags.sh "$(BUILD_DIR)/bd" @@ -457,12 +498,10 @@ diagrams-excalidraw: docs-dev: ./mint.sh dev -# Bazel (side-by-side with the Go toolchain; `go build`/`go test` do not need -# it). Regenerate BUILD.bazel files with gazelle and refresh the MODULE.bazel +# Regenerate BUILD.bazel files with gazelle and refresh the MODULE.bazel # use_repo list + MODULE.bazel.lock, then refresh the go_srcs filegroups that # source-scanning tests declare as data (tools/bazel/go_srcs.py). Run after # changing Go imports, go.mod, or packages. -BAZEL ?= bazel bazel-sync: $(BAZEL) run //:gazelle python3 tools/bazel/go_srcs.py @@ -498,7 +537,10 @@ help: @echo "Beads Makefile targets:" @echo " make build - Build the bd binary" @echo " make doctor-build - Diagnose build env (GOFLAGS/CGO/CC) for the ICU build trap" - @echo " make test - Run all tests" + @echo " make test - bazel test //... --config=ci (bazel.yml's test lane; BAZEL_FLAGS adds flags)" + @echo " make test-go - Plain go test via scripts/test.sh (inner loop; not what CI enforces)" + @echo " make check - testing.Short policy + nogo lint gate + make test" + @echo " make check-go - gofmt + testing.Short policy + make test-go (no Bazel)" @echo " make test-icu-path - Run opt-in ICU regex path tests (maintainer-only)" @echo " make test-full-cgo - Deprecated alias for make test-icu-path" @echo " make ci-pr-core - Run required PR core Go test wrapper" @@ -521,7 +563,8 @@ help: @echo " make install-force - Install bd, skipping the origin/main update check" @echo " make fmt - Format all Go files with gofmt" @echo " make fmt-check - Check Go formatting (for CI)" - @echo " make check-docs - Validate docs against CLI flags" + @echo " make check-docs - Bazel docsync + doc freshness tests, then the CLI flag check" + @echo " make check-docs-go - The same docs checks with plain go test" @echo " make api-gen - Regenerate HTTP API types from the OpenAPI spec" @echo " make api-check - OpenAPI drift gate (regenerate, diff-or-fail, spec tests)" @echo " make bazel-sync - Regenerate Bazel BUILD files and tidy MODULE.bazel (gazelle + mod tidy)" diff --git a/README.md b/README.md index 5526718f6..0984804ed 100644 --- a/README.md +++ b/README.md @@ -212,5 +212,5 @@ This is useful for: ## 📝 Documentation * [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Setup](docs/getting-started/ide-setup.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md) -* Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) | [Roadmap](ROADMAP.md) | [Contributor agent instructions](AGENTS.md) +* Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) (Bazel builds and tests beads: install [Bazelisk](https://github.com/bazelbuild/bazelisk), then `make test`) | [Roadmap](ROADMAP.md) | [Contributor agent instructions](AGENTS.md) * [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads) diff --git a/RELEASING.md b/RELEASING.md index a36816306..91a517832 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -138,7 +138,7 @@ Before starting a release: - [ ] `release/x.y.z` branch cut from a SHA green on `Main` **and** `Nightly Full Tests` (see [Release Branches](#release-branches)) -- [ ] All tests passing (`go test ./...`) +- [ ] All tests passing (`make test`, the Bazel test lane) - [ ] npm package tests passing (`cd npm-package && npm run test:all`) - [ ] **Upgrade smoke tests pass** (`make test-upgrade`) — see [Release Stability Gate](engdocs/RELEASE-STABILITY-GATE.md) - [ ] **Regression tests pass** (`make test-regression`) diff --git a/engdocs/TESTING.md b/engdocs/TESTING.md index bffa77fc5..46aab1118 100644 --- a/engdocs/TESTING.md +++ b/engdocs/TESTING.md @@ -1,9 +1,60 @@ # Testing Guide `TESTING.md` is the single authority for test commands, test selection, and -test design in this repository. Use the commands here for local work. For the -exact command behind a current CI check, inspect its workflow and corresponding -`Makefile` target; the CI audit and cleanup plan are dated maintainer context. +test design in this repository. Use the commands here for local work. + +## Building and Testing: Bazel Is the Gate + +Bazel is beads' build and test system. CI gates every pull request on the +`bazel test` lanes in `.github/workflows/bazel.yml`, and several checks exist +only as Bazel targets: nogo (go test's vet checks plus the golangci-lint +linters, `tools/nogo`), gofmt (`//scripts/repochecks:fmt_test`) and the +repository guards under `scripts/repochecks`. A plain `go test` runs none of +them, so it is an inner-loop convenience CI does not enforce; a change is +ready when its Bazel lanes pass. + +Install [Bazelisk](https://github.com/bazelbuild/bazelisk) as `bazel`; it +reads `.bazelversion`. The pre-commit hook (nogo on staged packages) and the +pre-push hook (the test lane) both need it. + +Where actions run is per machine, never committed: + +- **Contributors** read rbe-west's anonymous, read-only cache with + `--config=fork-cache`: everything CI already executed is a cache hit, misses + run on your machine, and nothing is uploaded. Make it the default with + `build --config=fork-cache` in your gitignored `.bazelrc.local`, or pass it + per command (`make test BAZEL_FLAGS=--config=fork-cache`). +- **Maintainers** with an rbe-west client certificate execute remotely with + `--config=remote-exec`; the executor endpoint and TLS lines go in the + gitignored `user.bazelrc` or `.bazelrc.local` (see the `.bazelrc` comments). +- **Agent hosts** whose `~/.bazelrc` names the executor need neither flag. + +Each lane, as bazel.yml runs it (add your `--config=fork-cache` or +`--config=remote-exec` when it is not your default): + +| Lane (bazel.yml job) | Command | Notes | +|---|---|---| +| Test (`bazel-test`) | `make test`, i.e. `bazel test //... --config=ci` | PR Core's selection: race, `-short`, skips. Includes nogo, gofmt and the repository guards. The default gate for every Go change. | +| Lint, all platforms | `make ci-pr-lint` | nogo natively plus the windows/amd64 and darwin/arm64 passes. `make lint-changed` covers only your changed packages. | +| Pure-Go (`bazel-pure`) | `bazel build --config=pure //cmd/bd:bd //cmd/bd:bd_test` | cgo off. The job's cmd/bd test subset (`PURE_CMD_BD_TESTS`), release cross-compile and js/wasm step are in bazel.yml. | +| Integration (`bazel-integration`) | `bazel test //... --config=integration` | The `integration`-tagged build. Runs with the read-only cache too. | +| Dolt server (`bazel-doltserver`) | `bazel test //... --config=doltserver` | Starts its own `dolt sql-server` from the pinned binary; no docker. | +| cmd/bd Dolt server (`bazel-cmd-dolt`) | `bazel test //cmd/bd:bd_dolt_server_test --config=doltserver-cmd` | 16 shards of the integration-tagged cmd/bd suite. | +| Embedded Dolt (`bazel-embedded`) | `bazel test //... --config=embedded` | Remote execution only in CI; locally it is slow. | +| Proxied server (`bazel-proxied`) | `bazel test //... --config=doltserver-proxied` | Remote execution only: 30 shards, each with a Dolt server. | +| Server-Dolt storage (`bazel-server-storage`) | `bazel test //... --config=doltserver-integration` | Remote execution only. | +| Docs | `make check-docs` | `//test/docsync:docsync_test` and `//scripts/repochecks:doc_freshness_test` in the test lane's configuration, then `scripts/check-doc-flags.sh` against the pinned release. | + +`make check` runs the testing.Short policy, `make ci-pr-lint` and +`make test`. After adding, removing or renaming Go files or changing imports +or `go.mod`, run `make bazel-sync` (gazelle, the `go_srcs` filegroups and +`MODULE.bazel`). + +The Makefile keeps plain-Go twins under explicit `-go` names: `make test-go` +(`./scripts/test.sh`), `make check-go` and `make check-docs-go`. They work +offline and without Bazel, but they are not what CI enforces. GitHub Actions +jobs that still run Go-native suites call the `-go` names, never `make test` +(`TestWorkflowsNameTheirTestEngine`). ## Choose the Smallest Useful Test @@ -17,23 +68,37 @@ a unit test: use the real boundary when the defect could live there. | Need | Run | When | |---|---|---| -| Docs-only validation | `git diff --check`, `go test -tags=gms_pure_go ./test/docsync`, and `./scripts/check-doc-freshness.sh` | For prose-only changes; add any generated-doc or surface-specific link check the changed paths require. Do not run the full Go suite merely because a Markdown file changed. | -| Focused red/green loop | `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...` | While writing or fixing one behavior. | -| Affected-package confidence | `./scripts/test.sh ./path/to/package/...` | After the focused test passes; include directly affected neighbors when their contract changed. | -| Final Go baseline | `make test` | Once after focused work on Go code is green. It applies the normal local build flags, coverage, and local skip handling. | +| Docs-only validation | `git diff --check` and `make check-docs` | For prose-only changes; add any generated-doc or surface-specific link check the changed paths require. Do not run the full suite merely because a Markdown file changed. | +| Focused red/green loop | `bazel test //path/to/package:package_test --config=ci --test_filter='^TestExactName$'`, or the plain-Go `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...` | While writing or fixing one behavior. The `go test` loop is fine here; the Bazel targets below are the gate. | +| Affected-package confidence | `bazel test //path/to/package/... --config=ci` | After the focused test passes; include directly affected neighbors when their contract changed. | +| Final gate | `make test` | Once after focused work on Go code is green: the whole test lane, mostly cache hits. | +| Another lane's risk | that lane's command from the table above | When the change touches what that lane covers (integration-tagged files, the Dolt server path, embedded Dolt, pure-Go builds). | | Named CI wrapper | `make ci-pr-core`, `make ci-pr-policy`, or `make ci-pr-lint` | Run the wrapper whose risk or surface is affected, or use it to reproduce that CI check. Do not run all three routinely for every edit. | | Hook shims against real timeout implementations | `nix flake check -L` (or `nix build .#checks..hook-timeout-backends -L`) | After changing the hook generator in `cmd/bd/hooks.go` (then `make githooks-regen`) or anything under `.githooks/`. Runs the tracked managed sections against GNU coreutils, uutils, busybox and toybox `timeout` — the multicalls also installed as `gtimeout` alone — with and without Perl, under dash, bash and busybox ash. About one deadline of wall time; needs no Go build. | Do not replace the focused loop with repeated full-suite runs. Run the final -`make test` once the affected Go tests are green. For docs-only changes, use +`make test` once the affected tests are green. For docs-only changes, use the docs, link, and diff checks instead. -## Commands and Local Environment +### Git Hooks -`./scripts/test.sh` is the normal runner. It sources `.buildflags`, creates an -isolated test environment, applies `.test-skip`, and defaults to a **25m -per-package** Go-test timeout. The timeout is a hang backstop, not a target -runtime. Override it only when diagnosing a legitimate slow path: +`make install` points `core.hooksPath` at `.githooks`. The pre-commit hook +formats staged Go files and runs nogo on their packages +(`make lint-changed LINT_CHANGED_SCOPE=staged`). The pre-push hook runs +`scripts/pre-push-suite.sh` for branch pushes whose commits change Go or +Bazel inputs: `bazel test //... --config=ci`, with `--config=remote-exec` +when some rc file names an executor and `--config=fork-cache` otherwise. +`BD_PREPUSH_SUITE=rbe|cache|go` picks the mode; `go` (and the fallback when +bazel is not installed) runs `make test-go` under a banner saying it is not +the suite CI gates on. + +## Plain `go test` (Inner Loop) + +`./scripts/test.sh` is the plain-Go runner behind `make test-go`. It sources +`.buildflags`, creates an isolated test environment, applies `.test-skip`, and +defaults to a **25m per-package** Go-test timeout. The timeout is a hang +backstop, not a target runtime. Override it only when diagnosing a legitimate +slow path: ```bash TEST_TIMEOUT=30m ./scripts/test.sh ./cmd/bd/... @@ -63,9 +128,9 @@ make test-cross-version make test-migration ``` -For a failing GitHub Actions check, follow the current workflow and its -`Makefile` target when exact reproduction matters. The local runner and CI -intentionally have different contracts in some cases. +For a failing GitHub Actions check, run the command of its bazel.yml lane +from the table above; for the jobs that are not Bazel lanes, follow the +workflow and its `Makefile` target. ### Test Environment and Readiness @@ -339,9 +404,10 @@ underlying failure is fixed. Before opening a PR: 1. For docs-only changes, run the applicable docs, link, freshness, and diff - checks; do not run the full Go suite by default. + checks; do not run the full suite by default. 2. For Go code, keep the focused and affected-package tests green, then run one - final `make test`. + final `make test` (the Bazel test lane), plus the lane of any other tier + the change touches. 3. Run only the named CI wrapper, specialized target, or risk gate required by the changed surface, or the one needed to reproduce a CI result. diff --git a/examples/formulas/primitives/README.md b/examples/formulas/primitives/README.md index ad52c67dc..879f10010 100644 --- a/examples/formulas/primitives/README.md +++ b/examples/formulas/primitives/README.md @@ -41,7 +41,7 @@ primitives are wired, not just that fixtures parse. Run with `make test`, or in isolation: ```sh -go test -tags gms_pure_go -run TestFormulaPrimitiveExamples ./cmd/bd/ +bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestFormulaPrimitiveExamples$' ``` ## What's NOT here diff --git a/scripts/BUILD.bazel b/scripts/BUILD.bazel index f19b1c2a6..cfaad6e93 100644 --- a/scripts/BUILD.bazel +++ b/scripts/BUILD.bazel @@ -40,12 +40,14 @@ go_test( "embedded_shard_count_test.go", "host_tools_test.go", "install_dolt_test.go", + "makefile_bazel_primary_test.go", "managed_local_lane_test.go", "migration_corpus_bazel_test.go", "nogo_lint_policy_test.go", "pr_lanes_bazel_coverage_test.go", "pr_preflight_test.go", "pr_risk_bazel_coverage_test.go", + "pre_push_suite_test.go", "pull_dolt_image_test.go", "rbe_worker_env_test.go", "release_script_test.go", diff --git a/scripts/README.md b/scripts/README.md index d9d99d6de..3bfa67bde 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -28,7 +28,7 @@ lint authority used by `bd preflight` in a Beads source checkout. Broad Go test wrappers also source `scripts/ci/lib/test-env.sh`, which creates a temporary HOME/XDG/Dolt root, isolates Git global/system config, clears runtime Beads/Dolt environment variables, and sets `BEADS_TEST_SKIP=dolt` before tests -run. This keeps local `make test` and `make ci-pr-core` results comparable to +run. This keeps local `make test-go` and `make ci-pr-core` results comparable to the fast PR-core contract even on shared agent hosts. Set `BEADS_TEST_ENV_RUN_DOLT=1` only when intentionally running the Dolt-dependent tests through these broad wrappers, or `BEADS_TEST_ENV_DISABLE=1` when debugging diff --git a/scripts/makefile_bazel_primary_test.go b/scripts/makefile_bazel_primary_test.go new file mode 100644 index 000000000..c94244f2e --- /dev/null +++ b/scripts/makefile_bazel_primary_test.go @@ -0,0 +1,135 @@ +package scripts_test + +import ( + "os" + "os/exec" + "path/filepath" + "regexp" + "strings" + "testing" +) + +// Bazel is beads' build and test system: bazel.yml's lanes gate every PR, +// and nogo (lint + vet), formatting and the repository guards exist only as +// Bazel targets. The primary make targets run the commands those lanes run, +// everywhere (GitHub Actions included), and each keeps a plain go twin under +// an explicit -go name. A workflow that runs a Go-native suite calls the -go +// name, so its engine is written in the workflow, not sniffed from the +// environment. + +const fakeMakeBazel = "/fake/bazel" + +// makeDryRun prints the recipe `make TARGET` would run, with BAZEL pointing +// at a fake path so a bazel invocation is recognizable. +func makeDryRun(t *testing.T, target string, env ...string) string { + t.Helper() + makeBin := requireHostTool(t, "make") + root := sourceRepoRoot(t) + cmd := exec.Command(makeBin, "--no-print-directory", "-n", + "-f", filepath.Join(root, "Makefile"), + "BAZEL="+fakeMakeBazel, + target) + cmd.Dir = root + for _, entry := range os.Environ() { + name, _, _ := strings.Cut(entry, "=") + switch name { + case "GITHUB_ACTIONS", "BAZEL_FLAGS", "MAKEFLAGS", "MAKELEVEL", "MFLAGS": + continue + } + cmd.Env = append(cmd.Env, entry) + } + cmd.Env = append(cmd.Env, env...) + out, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("make -n %s: %v\n%s", target, err, out) + } + return string(out) +} + +// goEngineRE matches a recipe line that tests with the Go toolchain. +var goEngineRE = regexp.MustCompile(`(^|\s)go test\s|scripts/test\.sh`) + +func TestMakePrimaryTargetsRunBazel(t *testing.T) { + for target, wants := range map[string][]string{ + "test": {fakeMakeBazel + " test //... --config=ci"}, + "check": { + "./scripts/check-testing-short.sh", + "./scripts/ci/pr-lint.sh", + fakeMakeBazel + " test //... --config=ci", + }, + "check-docs": { + fakeMakeBazel + " test //test/docsync:docsync_test //scripts/repochecks:doc_freshness_test --config=ci", + "./scripts/check-doc-flags.sh", + }, + } { + for _, env := range [][]string{nil, {"GITHUB_ACTIONS=true"}} { + t.Run(target+strings.Join(env, ","), func(t *testing.T) { + out := makeDryRun(t, target, env...) + for _, want := range wants { + if !strings.Contains(out, want) { + t.Errorf("make %s (env %v) does not run %q:\n%s", target, env, want, out) + } + } + if goEngineRE.MatchString(out) { + t.Errorf("make %s (env %v) runs go test instead of bazel:\n%s", target, env, out) + } + }) + } + } +} + +func TestMakeBazelFlagsReachEveryBazelTest(t *testing.T) { + out := makeDryRun(t, "test", "BAZEL_FLAGS=--config=fork-cache") + if want := fakeMakeBazel + " test --config=fork-cache //... --config=ci"; !strings.Contains(out, want) { + t.Errorf("make test with BAZEL_FLAGS does not run %q:\n%s", want, out) + } +} + +func TestMakeGoTwinsRunGoTest(t *testing.T) { + for target, want := range map[string]string{ + "test-go": "./scripts/test.sh", + "check-go": "./scripts/test.sh", + "check-docs-go": "go test -tags=gms_pure_go ./test/docsync", + } { + t.Run(target, func(t *testing.T) { + out := makeDryRun(t, target) + if !strings.Contains(out, want) { + t.Errorf("make %s does not run %q:\n%s", target, want, out) + } + if strings.Contains(out, fakeMakeBazel+" test") { + t.Errorf("make %s runs bazel test:\n%s", target, out) + } + }) + } +} + +// primaryMakeCallRE matches a call of a bazel-backed primary make target (not +// its -go twin or another target sharing the prefix). +var primaryMakeCallRE = regexp.MustCompile(`\bmake (test|check|check-docs)(\s|$|["'])`) + +// TestWorkflowsNameTheirTestEngine: a workflow runs bazel directly, or a +// Go-native suite through an explicit -go make target, never a primary name +// whose engine a reader would have to look up in the Makefile. +func TestWorkflowsNameTheirTestEngine(t *testing.T) { + root := sourceRepoRoot(t) + files, err := filepath.Glob(filepath.Join(root, ".github", "workflows", "*.y*ml")) + if err != nil || len(files) == 0 { + t.Fatalf("glob workflows: %v (%d files)", err, len(files)) + } + for _, file := range files { + body, err := os.ReadFile(file) + if err != nil { + t.Fatalf("read %s: %v", file, err) + } + for i, line := range strings.Split(string(body), "\n") { + trimmed := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "- ")) + if strings.HasPrefix(trimmed, "#") || strings.HasPrefix(trimmed, "name:") { + continue + } + if m := primaryMakeCallRE.FindStringSubmatch(line); m != nil { + t.Errorf("%s:%d calls `make %s`, which runs bazel; call `make %s-go` for the Go-native suite or bazel directly", + filepath.Base(file), i+1, m[1], m[1]) + } + } + } +} diff --git a/scripts/pre-push-suite.sh b/scripts/pre-push-suite.sh new file mode 100755 index 000000000..9041d5527 --- /dev/null +++ b/scripts/pre-push-suite.sh @@ -0,0 +1,140 @@ +#!/usr/bin/env bash +# The push-time test suite, run by .githooks/pre-push when a pushed branch +# changes Go or Bazel inputs: bazel.yml's test lane, `bazel test //... +# --config=ci`, with the action keys CI uses, so a push reuses what CI and +# earlier pushes already computed. +# +# BD_PREPUSH_SUITE picks where it runs (default auto): +# auto remote-exec when bazel's effective options name a remote executor +# (a maintainer's .bazelrc.local, an agent host's ~/.bazelrc); +# fork-cache when bazel is installed without one; go when bazel is +# not installed. +# rbe --config=remote-exec; fails when no rc file names an executor (the +# suite would otherwise compile and run on this machine). +# cache --config=fork-cache: the anonymous read-only cache; misses run on +# this machine and nothing is uploaded. +# go make test-go (plain go test through scripts/test.sh), under a +# banner saying it is not what CI enforces. +# BAZEL and MAKE override the binaries. Bypass the hook: git push --no-verify. +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$repo_root" + +bazel_bin="${BAZEL:-bazel}" +make_bin="${MAKE:-make}" +mode="${BD_PREPUSH_SUITE:-auto}" +executor="" +# Why the push runs plain go test instead of bazel, and how to get bazel back. +go_why="BD_PREPUSH_SUITE=go" +go_fix="unset BD_PREPUSH_SUITE to run the bazel suite" + +# The go suite is not what CI enforces: bazel.yml gates on bazel test, whose +# nogo lint/vet, formatting and repository-guard targets have no go test +# counterpart. Say so loudly, with the reason, so a green push is not read as +# CI parity. +announce_go_suite() { + { + echo "pre-push: ========================================================================" + echo "pre-push: running make test-go (plain go test): NOT the bazel suite CI gates on." + echo "pre-push: why: $go_why" + echo "pre-push: CI runs bazel test //... --config=ci (.github/workflows/bazel.yml); a push" + echo "pre-push: that passes here can still fail there (nogo lint/vet, formatting, guards)." + echo "pre-push: fix: $go_fix" + echo "pre-push: ========================================================================" + } >&2 +} + +# The remote executor some rc file names for this workspace, empty for none: +# the last non-empty --remote_executor among the rc options Bazel reads +# (system, workspace with .bazelrc.local and user.bazelrc, home) and the +# remote-exec config's definitions, from `bazel info --announce_rc`. Bazel's +# own reading of every rc, not a grep of one file, so an agent host's +# ~/.bazelrc executor counts. Fails, printing Bazel's error, when Bazel cannot +# read its options. +effective_remote_executor() { + local announced + if ! announced="$("$bazel_bin" info --announce_rc --config=remote-exec release 2>&1 >/dev/null)"; then + printf '%s\n' "$announced" >&2 + return 1 + fi + printf '%s\n' "$announced" | awk ' + /^INFO: (Reading rc options|Options provided by the client)/ { section = 1; next } + /^[^[:space:]]/ { section = 0 } + !section && !/^INFO: Found applicable config definition [^ ]*:remote-exec / { next } + { + for (i = 1; i <= NF; i++) { + value = "" + if ($i ~ /^--remote_executor=/) { + value = substr($i, length("--remote_executor=") + 1) + } else if ($i == "--remote_executor" && i < NF) { + value = $(i + 1) + } + if (value != "") { + executor = value + } + } + } + END { print executor }' +} + +# Sets $executor, or fails the push: an unreadable option set is no evidence +# for either mode. +probe_executor() { + if ! executor="$(effective_remote_executor)"; then + echo "pre-push: bazel info could not read this workspace's options (above); fix the rc, or set BD_PREPUSH_SUITE=rbe|cache|go" >&2 + exit 2 + fi +} + +have_bazel() { + command -v "$bazel_bin" >/dev/null 2>&1 +} + +case "$mode" in +auto) + if ! have_bazel; then + go_why="bazel is not installed" + go_fix="install bazelisk as bazel (CONTRIBUTING.md \"Building and testing\")" + mode=go + else + probe_executor + if [ -n "$executor" ]; then + mode=rbe + else + mode=cache + fi + fi + ;; +go | cache) ;; +rbe) + if have_bazel; then + probe_executor + if [ -z "$executor" ]; then + echo "pre-push: BD_PREPUSH_SUITE=rbe but no rc file names a --remote_executor; configure one (engdocs/TESTING.md \"Building and testing\") or use BD_PREPUSH_SUITE=cache|go" >&2 + exit 2 + fi + fi + ;; +*) + echo "pre-push: BD_PREPUSH_SUITE=$mode is not one of auto, rbe, cache, go" >&2 + exit 2 + ;; +esac + +case "$mode" in +go) + announce_go_suite + exec "$make_bin" test-go + ;; +rbe) config=remote-exec ;; +cache) config=fork-cache ;; +esac + +if ! have_bazel; then + echo "pre-push: BD_PREPUSH_SUITE=$mode needs bazel on PATH; install bazelisk or use BD_PREPUSH_SUITE=go" >&2 + exit 2 +fi + +echo "pre-push: bazel test //... --config=ci --config=$config${executor:+ on $executor} (BD_PREPUSH_SUITE=go runs plain go test instead)" >&2 +exec "$bazel_bin" test //... --config=ci "--config=$config" diff --git a/scripts/pre_push_suite_test.go b/scripts/pre_push_suite_test.go new file mode 100644 index 000000000..9e4a96703 --- /dev/null +++ b/scripts/pre_push_suite_test.go @@ -0,0 +1,157 @@ +package scripts_test + +import ( + "os" + "os/exec" + "path/filepath" + "strings" + "testing" +) + +// scripts/pre-push-suite.sh is the push-time suite .githooks/pre-push runs +// when a pushed branch changes Go or Bazel inputs: bazel.yml's test lane +// (`bazel test //... --config=ci`), remotely when some rc names an executor, +// else through the read-only fork cache. Plain go test runs only when bazel +// cannot (or BD_PREPUSH_SUITE=go asks for it), and then under a banner, so +// a green push is never read as CI parity. + +type prePushSuiteRun struct { + out string + bazel string + make string + exitErr error +} + +// runPrePushSuite runs the suite with fake bazel and make that log their +// arguments. announce is what the fake `bazel info --announce_rc` prints to +// stderr; bazel "missing" points BAZEL at a path that does not exist. +func runPrePushSuite(t *testing.T, bazel, announce string, env ...string) prePushSuiteRun { + t.Helper() + bash := requireHostTool(t, "bash") + dir := t.TempDir() + bazelLog := filepath.Join(dir, "bazel.log") + makeLog := filepath.Join(dir, "make.log") + writeExecutable := func(name, body string) string { + path := filepath.Join(dir, name) + if err := os.WriteFile(path, []byte("#!/usr/bin/env bash\n"+body), 0o755); err != nil { + t.Fatal(err) + } + return path + } + fakeBazel := writeExecutable("bazel", `if [ "$1" = info ]; then printf '%s\n' "$FAKE_ANNOUNCE" >&2; echo release 9; exit 0; fi +printf '%s\n' "$*" >>"`+bazelLog+`" +`) + fakeMake := writeExecutable("make", `printf '%s\n' "$*" >>"`+makeLog+`" +`) + if bazel == "missing" { + fakeBazel = filepath.Join(dir, "no-such-bazel") + } + + cmd := exec.Command(bash, filepath.Join(sourceRepoRoot(t), "scripts", "pre-push-suite.sh")) + for _, entry := range os.Environ() { + if name, _, _ := strings.Cut(entry, "="); name == "BD_PREPUSH_SUITE" { + continue + } + cmd.Env = append(cmd.Env, entry) + } + cmd.Env = append(cmd.Env, "BAZEL="+fakeBazel, "MAKE="+fakeMake, "FAKE_ANNOUNCE="+announce) + cmd.Env = append(cmd.Env, env...) + out, err := cmd.CombinedOutput() + read := func(path string) string { + data, _ := os.ReadFile(path) + return strings.TrimSpace(string(data)) + } + return prePushSuiteRun{out: string(out), bazel: read(bazelLog), make: read(makeLog), exitErr: err} +} + +const announceWithExecutor = `INFO: Reading rc options for 'info' from /home/u/.bazelrc: + Inherited 'build' options: --remote_executor=grpcs://rbe.example:443 --jobs=64` + +const announceWithoutExecutor = `INFO: Reading rc options for 'info' from /w/.bazelrc: + Inherited 'common' options: --enable_bzlmod` + +func TestPrePushSuiteRunsBazelTestLane(t *testing.T) { + for _, tc := range []struct { + name, announce string + env []string + want string + }{ + {"auto with an executor", announceWithExecutor, nil, "test //... --config=ci --config=remote-exec"}, + {"auto without an executor", announceWithoutExecutor, nil, "test //... --config=ci --config=fork-cache"}, + {"explicit cache", announceWithExecutor, []string{"BD_PREPUSH_SUITE=cache"}, "test //... --config=ci --config=fork-cache"}, + {"explicit rbe", announceWithExecutor, []string{"BD_PREPUSH_SUITE=rbe"}, "test //... --config=ci --config=remote-exec"}, + } { + t.Run(tc.name, func(t *testing.T) { + run := runPrePushSuite(t, "present", tc.announce, tc.env...) + if run.exitErr != nil { + t.Fatalf("suite failed: %v\n%s", run.exitErr, run.out) + } + if run.bazel != tc.want { + t.Errorf("bazel ran %q, want %q\n%s", run.bazel, tc.want, run.out) + } + if run.make != "" { + t.Errorf("make ran %q; the bazel suite needs no go fallback\n%s", run.make, run.out) + } + }) + } +} + +func TestPrePushSuiteRbeWithoutExecutorFails(t *testing.T) { + run := runPrePushSuite(t, "present", announceWithoutExecutor, "BD_PREPUSH_SUITE=rbe") + if run.exitErr == nil || run.bazel != "" { + t.Fatalf("BD_PREPUSH_SUITE=rbe without an executor: err %v, bazel ran %q\n%s", run.exitErr, run.bazel, run.out) + } +} + +func TestPrePushSuiteGoFallbackIsAnnounced(t *testing.T) { + for _, tc := range []struct { + name, bazel, why string + env []string + }{ + {"bazel missing", "missing", "bazel is not installed", nil}, + {"explicit go", "present", "BD_PREPUSH_SUITE=go", []string{"BD_PREPUSH_SUITE=go"}}, + } { + t.Run(tc.name, func(t *testing.T) { + run := runPrePushSuite(t, tc.bazel, announceWithExecutor, tc.env...) + if run.exitErr != nil { + t.Fatalf("suite failed: %v\n%s", run.exitErr, run.out) + } + if run.make != "test-go" || run.bazel != "" { + t.Errorf("ran make %q, bazel %q; want make test-go only\n%s", run.make, run.bazel, run.out) + } + for _, want := range []string{"NOT the bazel suite CI gates on", "why: " + tc.why, "bazel test //... --config=ci"} { + if !strings.Contains(run.out, want) { + t.Errorf("go fallback banner lacks %q:\n%s", want, run.out) + } + } + }) + } +} + +func TestPrePushSuiteRejectsUnknownMode(t *testing.T) { + run := runPrePushSuite(t, "present", announceWithExecutor, "BD_PREPUSH_SUITE=sometimes") + if run.exitErr == nil || run.bazel != "" || run.make != "" { + t.Fatalf("unknown mode: err %v, bazel %q, make %q\n%s", run.exitErr, run.bazel, run.make, run.out) + } +} + +// The hook runs the suite only for branch pushes whose commits change Go or +// Bazel inputs; a tag push, a deletion, or a docs-only push skips it. +func TestPrePushHookRunsSuiteOnlyForGoChanges(t *testing.T) { + body := readPolicyFile(t, sourceRepoRoot(t), ".githooks/pre-push") + for _, want := range []string{ + `"$repo_root/scripts/pre-push-suite.sh" managed { + t.Errorf(".githooks/pre-push must run the suite before the managed beads section") + } +}