diff --git a/AGENTS.md b/AGENTS.md index b17bc9cad..ad847038f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,12 +41,12 @@ echo 'Updated text' | bd update --description=- ## Testing Commands (No Ambiguity) - Default local test command: `make test` (or `./scripts/test.sh`). -- Full CGO-enabled suite: `make test-full-cgo` (or `./scripts/test-cgo.sh ./...`). -- On macOS, do **not** run raw `CGO_ENABLED=1 go test ./...` unless ICU flags are set; use the script/Make target above. -- If you need package- or test-scoped CGO runs: +- Opt-in ICU regex path: `make test-icu-path` (or `./scripts/test-icu-path.sh ./...`). +- This ICU path is maintainer-only and not part of normal validation; `make test-full-cgo` and `./scripts/test-cgo.sh` are deprecated aliases. +- For package- or test-scoped shipped-config CGO runs, prefer: ```bash -./scripts/test-cgo.sh ./cmd/bd/... -./scripts/test-cgo.sh -run '^TestName$' ./cmd/bd/... +CGO_ENABLED=1 go test -tags gms_pure_go ./cmd/bd/... +CGO_ENABLED=1 go test -tags gms_pure_go -run '^TestName$' ./cmd/bd/... ``` ## Non-Interactive Shell Commands diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md index 40c8f4b96..d93d4d7f2 100644 --- a/AGENT_INSTRUCTIONS.md +++ b/AGENT_INSTRUCTIONS.md @@ -10,7 +10,7 @@ This document contains detailed operational instructions for AI agents working o - **Go version**: 1.24+ - **Linting**: `golangci-lint run ./...` (baseline warnings documented in [docs/LINTING.md](docs/LINTING.md)) -- **Testing**: All new features need tests (`make test` for local baseline, `make test-full-cgo` when validating full CGO paths) +- **Testing**: All new features need tests (`make test` for the normal local/CI path, `make test-icu-path` only when intentionally exercising the opt-in ICU regex path) - **Documentation**: Update relevant .md files ### File Organization @@ -66,7 +66,7 @@ into temp repos and produce flaky test behavior. ### Before Committing 1. **Run tests**: `make test` (or `./scripts/test.sh`) - - For full CGO validation: `make test-full-cgo` + - Only if intentionally exercising the ICU regex path: `make test-icu-path` 2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings) 3. **Update docs**: If you changed behavior, update README.md or other docs 4. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed @@ -143,7 +143,7 @@ This is enforced by pre-use hooks. If you try `gh pr create`, it will be blocked 1. **File beads issues for any remaining work** that needs follow-up 2. **Ensure all quality gates pass** (only if code changes were made): - Run `make lint` or `golangci-lint run ./...` (if pre-commit installed: `pre-commit run --all-files`) - - Run `make test` (and `make test-full-cgo` when CGO-relevant code changed) + - Run `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path) - File P0 issues if quality gates are broken 3. **Update beads issues** - close finished work, update status 4. **PUSH TO REMOTE - NON-NEGOTIABLE** - This step is MANDATORY. Execute ALL commands below: @@ -313,8 +313,8 @@ make install # Test (local baseline) make test -# Test with full CGO-enabled suite (local/CI parity) -make test-full-cgo +# Optional ICU regex path smoke (maintainer-only, not normal validation) +make test-icu-path # Coverage run go test -coverprofile=coverage.out ./... @@ -395,7 +395,7 @@ This handles the entire release workflow automatically, including waiting ~5 min 1. Bump version: `./scripts/bump-version.sh --commit` 2. Update CHANGELOG.md with release notes -3. Run tests: `make test` (and `make test-full-cgo` for CGO-related changes) +3. Run tests: `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path) 4. Push version bump: `git push origin main` 5. Tag release: `git tag v && git push origin v` 6. Update Homebrew: `./scripts/update-homebrew.sh ` (waits for GitHub Actions) diff --git a/Makefile b/Makefile index 19bfba3f3..1f01c660c 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ SHELL := $(subst cmd,bin,$(subst git.exe,bash.exe,$(GIT_BASH))) endif endif -.PHONY: all build test test-full-cgo test-regression test-upgrade test-cross-version test-migration bench bench-quick clean install install-force help check-up-to-date fmt fmt-check +.PHONY: all build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration bench bench-quick clean install install-force help check-up-to-date fmt fmt-check # Default target all: build @@ -43,7 +43,8 @@ endif # gms_pure_go tells go-mysql-server to use Go's stdlib regex instead of # ICU-backed go-icu-regex. This eliminates the ICU shared-library runtime # dependency, making release binaries portable across Linux distros. -# ICU flags are only needed for test-cgo.sh (which exercises the ICU path). +# ICU flags are only needed for scripts/test-icu-path.sh (which exercises the +# opt-in ICU regex path). BUILD_TAGS := gms_pure_go # Build the bd binary @@ -64,11 +65,18 @@ test: @echo "Running tests..." @TEST_COVER=1 ./scripts/test.sh -# Run full CGO-enabled test suite (no skip list). -# On macOS, auto-configures ICU include/link flags. +# 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. +test-icu-path: + @echo "Running opt-in ICU regex path tests..." + @./scripts/test-icu-path.sh ./... + +# Deprecated compatibility alias. Keep forwarding so old local notes still work, +# but make the opt-in ICU nature explicit. test-full-cgo: - @echo "Running full CGO-enabled tests..." - @./scripts/test-cgo.sh ./... + @echo "WARNING: make test-full-cgo is deprecated; use make test-icu-path for the explicit ICU-only path." >&2 + @$(MAKE) test-icu-path # Run differential regression tests (baseline v0.49.6 vs current worktree). # Downloads baseline binary on first run; cached in ~/Library/Caches/beads-regression/. @@ -191,7 +199,8 @@ help: @echo "Beads Makefile targets:" @echo " make build - Build the bd binary" @echo " make test - Run all tests" - @echo " make test-full-cgo - Run full CGO-enabled test suite" + @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 test-regression - Run differential regression tests (baseline vs candidate)" @echo " make test-upgrade - Run upgrade smoke tests (release stability gate)" @echo " make test-cross-version - Run cross-version smoke tests (last 30 tags)" diff --git a/docs/ICU-POLICY.md b/docs/ICU-POLICY.md index b7602c6f0..7d912adff 100644 --- a/docs/ICU-POLICY.md +++ b/docs/ICU-POLICY.md @@ -60,11 +60,14 @@ Every build path that produces a binary for users must include `-tags gms_pure_g ## Where `gms_pure_go` Is Intentionally Omitted -`scripts/test-cgo.sh` omits `gms_pure_go` as a local developer tool for -exercising the ICU code path in `go-mysql-server` on demand. CI no longer -does this: upstream confirmed (dolthub/go-mysql-server#3506) that -`-tags=gms_pure_go` is the sanctioned escape hatch, so we test the -configuration we ship. +`scripts/test-icu-path.sh` omits `gms_pure_go` as an explicit, opt-in local +developer tool for exercising the ICU code path in `go-mysql-server` on +demand. CI no longer does this: upstream confirmed +(dolthub/go-mysql-server#3506) that `-tags=gms_pure_go` is the sanctioned +escape hatch, so we test the configuration we ship. + +The older name `scripts/test-cgo.sh` is retained only as a deprecated shim +that warns and forwards to `scripts/test-icu-path.sh`. ## Post-Build Verification @@ -96,7 +99,8 @@ Once the upstream PR merges, remove the `replace` directive from `go.mod`. ICU linkage. The post-build checks will catch it, but don't do it. 3. **Installing `libicu-dev` in release or CI test workflows** -- only - needed for local, on-demand developer testing via `scripts/test-cgo.sh`. + needed for local, on-demand developer testing via + `scripts/test-icu-path.sh`. Neither release builds nor the CI test matrix link ICU; both must not depend on ICU being installed. diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index 4e7dd78c9..5ad388f87 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -239,8 +239,9 @@ Linux (Fedora/RHEL): sudo dnf install -y libzstd-devel ``` -> **For CI / test contributors only:** If you need to run `scripts/test-cgo.sh` -> (which exercises the ICU code path), install ICU headers: +> **For maintainers only:** If you intentionally need to run +> `scripts/test-icu-path.sh` (which exercises the leftover ICU code path), +> install ICU headers: > `brew install icu4c` (macOS) or `sudo apt-get install -y libicu-dev` (Linux). > This is not needed for normal development. diff --git a/docs/TESTING.md b/docs/TESTING.md index 1193ab23a..740bb3aca 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -22,8 +22,8 @@ make test # Or directly: ./scripts/test.sh -# Run full CGO-enabled suite (no skip list) -make test-full-cgo +# Run opt-in ICU regex path tests (maintainer-only, not normal validation) +make test-icu-path # Run specific package ./scripts/test.sh ./cmd/bd/... @@ -125,7 +125,7 @@ When running tests during development: - Automatically skips known broken tests - Uses appropriate timeouts - Consistent with CI/CD - - For full CGO validation, use `./scripts/test-cgo.sh` (or `make test-full-cgo`) + - Only if intentionally exercising the ICU regex path, use `./scripts/test-icu-path.sh` (or deprecated `make test-full-cgo`) 2. **Target specific tests when possible:** ```bash diff --git a/scripts/test-cgo.sh b/scripts/test-cgo.sh index 541a0d620..82525005a 100755 --- a/scripts/test-cgo.sh +++ b/scripts/test-cgo.sh @@ -1,27 +1,9 @@ #!/usr/bin/env bash set -euo pipefail -# Run full CGO-enabled tests with platform-specific prerequisites. -# Use this instead of raw `CGO_ENABLED=1 go test ...` on macOS. +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -export CGO_ENABLED=1 +echo "WARNING: scripts/test-cgo.sh is deprecated." >&2 +echo "WARNING: Use $SCRIPT_DIR/test-icu-path.sh for the explicit ICU-only path, or ./scripts/test.sh for normal validation." >&2 -if [[ "$(uname)" == "Darwin" ]]; then - ICU_PREFIX="$(brew --prefix icu4c 2>/dev/null || true)" - if [[ -z "$ICU_PREFIX" ]]; then - echo "ERROR: Homebrew icu4c not found." >&2 - echo "Install it with: brew install icu4c" >&2 - exit 1 - fi - - export CGO_CFLAGS="${CGO_CFLAGS:+$CGO_CFLAGS }-I${ICU_PREFIX}/include" - export CGO_CPPFLAGS="${CGO_CPPFLAGS:+$CGO_CPPFLAGS }-I${ICU_PREFIX}/include" - export CGO_LDFLAGS="${CGO_LDFLAGS:+$CGO_LDFLAGS }-L${ICU_PREFIX}/lib -Wl,-rpath,${ICU_PREFIX}/lib" -fi - -if [[ $# -eq 0 ]]; then - set -- ./... -fi - -echo "Running CGO tests: go test $*" >&2 -go test "$@" +exec "$SCRIPT_DIR/test-icu-path.sh" "$@" diff --git a/scripts/test-icu-path.sh b/scripts/test-icu-path.sh new file mode 100755 index 000000000..4602f12e1 --- /dev/null +++ b/scripts/test-icu-path.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Run the opt-in ICU regex path tests. +# This is intentionally NOT the normal validation path for beads. The shipped +# and CI-tested configuration uses -tags gms_pure_go instead. + +echo "WARNING: scripts/test-icu-path.sh intentionally exercises the ICU-only regex path." >&2 +echo "WARNING: This is maintainer-only and not part of normal validation; use ./scripts/test.sh or make test for the shipped path." >&2 + +export CGO_ENABLED=1 + +if [[ "$(uname)" == "Darwin" ]]; then + ICU_PREFIX="$(brew --prefix icu4c 2>/dev/null || true)" + if [[ -z "$ICU_PREFIX" ]]; then + echo "ERROR: Homebrew icu4c not found." >&2 + echo "Install it with: brew install icu4c" >&2 + exit 1 + fi + + export CGO_CFLAGS="${CGO_CFLAGS:+$CGO_CFLAGS }-I${ICU_PREFIX}/include" + export CGO_CPPFLAGS="${CGO_CPPFLAGS:+$CGO_CPPFLAGS }-I${ICU_PREFIX}/include" + export CGO_LDFLAGS="${CGO_LDFLAGS:+$CGO_LDFLAGS }-L${ICU_PREFIX}/lib -Wl,-rpath,${ICU_PREFIX}/lib" +fi + +if [[ $# -eq 0 ]]; then + set -- ./... +fi + +echo "Running ICU regex path tests: go test $*" >&2 +go test "$@" diff --git a/scripts/test.sh b/scripts/test.sh index 864a85130..88f4d990f 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -8,7 +8,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" SKIP_FILE="$REPO_ROOT/.test-skip" # Default test path uses the same pure-Go regex build as user-facing binaries. -# ICU coverage remains available via scripts/test-cgo.sh. +# Opt-in ICU-path coverage remains available via scripts/test-icu-path.sh. export GOFLAGS="${GOFLAGS:+$GOFLAGS }-tags=gms_pure_go" # Build skip pattern from .test-skip file