Development workflow

This page captures the build/test/PR loop in the way the repository expects. Policy-level rules live in AGENTS.md; this page is operational.

Branching

• The default branch is master. Long-lived release branches use the release-X.Y pattern. Day-to-day development happens on topic branches off master.
• The repo squashes on merge — keep your local history small and focused. Avoid git push --force on shared branches; prefer --force-with-lease if it is unavoidable.

Local build

# Default: build the TiDB SQL server
make
# Or other binaries
make build_br
make build_lightning
make build_dumpling
make build_tools

Outputs land in bin/. The default make target depends on Makefile.common's server target, which go builds cmd/tidb-server/.

When make bazel_prepare is required

The repo's BUILD files are generated by Gazelle (via make bazel_prepare). Re-run it whenever the Quick Decision Matrix in AGENTS.md says so:

• A new workspace or fresh clone.
• Bazel-related files changed (WORKSPACE, DEPS.bzl, BUILD.bazel, MODULE.bazel, MODULE.bazel.lock).
• Any Go source file is added/removed/renamed/moved.
• A new top-level func TestXxx(t *testing.T) is added in an existing *_test.go.
• go.mod or go.sum changed.
• Bazel test targets were modified (e.g., shard_count, srcs).

The operational checklist is in .agents/skills/tidb-bazel-prepare-gate. Re-running locally:

make bazel_prepare

make bazel_lint_changed is intentionally not part of the default flow — it is heavy and CI-only unless the user asks for it.

Code/test/PR loop

1. Implement. Match local style. Don't reformat unrelated code. If you're adding a new feature, look for an AGENTS.md deeper in the tree or a doc.go package comment first.
2. Generate. If you touched the parser (pkg/parser/parser.y), the hint parser, vectorized expression generator, or anything regenerated by go generate ./..., run the corresponding make target (make parser, make gogenerate).
3. Validate. Pick the smallest test scope that proves correctness. The validation matrix in AGENTS.md -> Task -> Validation Matrix maps subsystems to required tests. See Testing for the commands.
4. Lint. make lint (revive + dashboard linter). Many CI failures are revive findings.
5. Tidy. go mod tidy if you changed dependencies; make bazel_prepare if you triggered any rule above.
6. Format. make fmt.
7. Self-review. Re-read your diff. Strip dead code, debugging prints, and TODOs that aren't actionable.

Verification profiles

The .agents/skills/tidb-verify-profile skill defines:

• WIP — fast subset, used during local iteration. Skip linters, run only the most directly affected tests.
• Ready — required before claiming task completion ("fixed", "done", "ready for review"). Includes make lint for code changes.
• Heavy — full suite (CI-equivalent). Use only when CI flagged something you can't reproduce otherwise.

If you say "ready for review" or "all tests pass", you must have run Ready first. The trigger phrases for Ready are listed in AGENTS.md's Quick Decision Matrix.

Opening a PR

1. Use the template:

   gh pr create -T .github/pull_request_template.md

2. Title format: pkg [, pkg2]: what is changed or *: what is changed.
3. Description must include one line Issue Number: close #<id> (or ref #<id>). Don't delete the HTML comment markers — CI parses them.
4. Fill the Tests section. Quote the exact commands you ran.
5. Add component labels and a severity label if it's a bug fix.

After a PR is open

• Address review comments with follow-up commits, not force-pushes.
• The CI pipeline (Prow + GitHub Actions in .github/workflows/) runs the equivalent of make bazel_test. If something flakes, look at the test output before assuming it's the test's fault — docs/agents/tidb-test-diff-triage is the runbook for triaging unexpected diffs.