Tooling

The project leans heavily on Make, custom Go generators, and golangci-lint. This page is a tour of what each tool does and where the source is.

Make

The Makefile is the canonical entry point for everything CI does. Useful targets:

Target	What it does
make (default)	Install build deps, run codegen, build all binaries
make bins	Build binaries only
make proto	Regenerate proto stubs
make update-go-api	Pull latest go.temporal.io/api
make lint-code	Run golangci-lint with the project rules
make fmt-imports	Group/sort imports the way the linter wants
make unit-test	All unit tests with -tags test_dep
make integration-test	Persistence-backed tests
make functional-test	Functional E2E tests in tests/
make start-dependencies	Bring up Cassandra/MySQL/PG/ES via Docker Compose
make stop-dependencies	Tear them down
make start-sqlite-file	Run the server against an on-disk SQLite
make copyright	Verify license headers

There are many more — open the file and read the section comments at the top.

Code generators (cmd/tools)

The repository ships its own generators because some patterns are too project-specific for off-the-shelf tools. They live in cmd/tools/:

Tool	Purpose
cmd/tools/protogen/	Drives protoc for both internal and external proto files.
cmd/tools/protoc-gen-go-chasm/	Custom protoc plugin emitting CHASM glue code.
cmd/tools/genrpcserverinterceptors/	Generates server-side RPC interceptors per service.
cmd/tools/genrpcwrappers/	Generates client-side wrapper code (retry / rate-limit / metrics).
cmd/tools/gendynamicconfig/	Validates and generates dynamic-config helper tables.
cmd/tools/gensearchattributehelpers/	Emits typed accessors for search attributes.
cmd/tools/getproto/	Pins / fetches proto submodules.
cmd/tools/optimize-test-sharding/	Computes a near-optimal CI test shard plan.
cmd/tools/parallelize/	Runs sub-tools in parallel.
cmd/tools/test-runner/	Wraps go test to collect junit / coverage output.
cmd/tools/flakereport/	Aggregates junit results and reports flakes to Slack.
cmd/tools/codegen/	Misc. Go template-driven generation.
cmd/tools/fairsim/	Simulator for the Matching fairness scheduler — see service/matching/fairness.md.
cmd/tools/cassandra/	temporal-cassandra-tool — schema setup / migration for Cassandra.
cmd/tools/sql/	temporal-sql-tool — schema setup / migration for MySQL / PG / SQLite.
cmd/tools/elasticsearch/	Setup helpers for the visibility ES index.
cmd/tools/check-dependencies/	Sanity-checks that go.mod / go.sum are clean.
cmd/tools/tdbg/	The operator CLI for cluster diagnostics. See Debugging.
cmd/tools/ci-notify/	Slack notifications from CI workflows.

Run go run ./cmd/tools/<tool>/... for any of them; most are also wrapped behind a Make target.

Linting

.github/.golangci.yml configures golangci-lint. Notable enabled linters:

• errcheck — every error must be handled.
• staticcheck — broad correctness checks.
• revive — style.
• gocritic — additional code-smell checks.
• testifylint — enforces the testify conventions documented in Testing.

make lint-code runs the full set. The lint config disables some checks that are noisy on generated code (e.g. inside api/).

Schema migrations

Schema lives in schema/. New schema versions go through temporal-sql-tool / temporal-cassandra-tool:

./temporal-sql-tool --plugin postgres12 setup-schema -v 0.0
./temporal-sql-tool --plugin postgres12 update-schema -d ./schema/postgresql/v12/temporal/versioned

The schema definition under each backend's directory is broken up by "namespace" (temporal/ for primary store, visibility/ for the visibility store) and by version. Adding a column is a new versioned migration file.

CI

Workflow files live in .github/workflows/. The interesting ones:

• lint.yml — make lint-code
• unit-test-coverage.yml
• functional-test-*.yml — functional tests sharded by package
• integration-tests-*.yml — integration tests against each persistence backend
• release-cut.yml — tagged releases
• flakes.yml — calls cmd/tools/flakereport to post flake stats

Reusable composite actions live under .github/actions/. Don't duplicate setup steps across workflows; reach for the existing actions first.

Editor configuration

• .vscode/ — workspace defaults, keep them.
• .cursor/ — Cursor rule prompts (mirroring AGENTS.md).
• .claude/ — Claude rule prompts.

The editor configs are intentionally kept in-tree so any contributor's editor picks up the same conventions.