Development workflow

The standard branch / code / test / PR / merge cycle for this repository.

Branching model

The project uses a single long-lived branch — main — and feature branches are short-lived. Tags (v1.x.y) are cut from main for releases.

git checkout -b my-feature main
# ... edit ...
git push -u origin my-feature
# Open PR targeting main

There are also release candidate tags (v1.32.0-156.0-rc.20260429115711 style) created automatically by tooling — do not push these manually.

The change loop

1. Pick the right level of test feedback. Unit tests run in seconds; integration / functional tests take minutes. Use the fastest signal that catches your bug:

   go test -tags test_dep ./service/history/workflow -run TestMutableStateImpl -v

2. Iterate locally. Most workflow-engine changes can be exercised end-to-end against the in-process cluster used by tests/.

3. Lint and format.

   make fmt-imports
   make lint-code

4. Regenerate code where needed. After editing a .proto file:

   make proto

   After editing anything tagged //go:generate:

   go generate ./path/to/pkg/...

5. Run the broader suite if the change is invasive.

   make unit-test
   make integration-test
   make functional-test

Commit hygiene

• Follow Chris Beams' guide to commit messages, as called out in CONTRIBUTING.md.
• Every PR title becomes the squashed commit message — keep it descriptive.
• Don't squash by hand on the branch; let the maintainer "Squash and merge" through GitHub.

CI

Every PR runs a matrix of jobs defined in .github/workflows/:

Workflow	Triggered on
lint	every PR — runs make lint-code
unit-test-coverage	every PR — runs unit tests with coverage
functional-test-*	every PR — sharded functional tests
integration-tests-*	every PR — Cassandra / SQL persistence checks
release-cut	on tag push — produces release artifacts

If a CI job goes flaky, the tools/flakereport/ tool aggregates results into Slack via the workflow at .github/workflows/flakes.yml. 42 commits in the last 90 days touched the flakereport tooling alone — flakiness is taken seriously.

Merging

PRs are merged by maintainers via GitHub's "Squash and merge" once:

• All CODEOWNER reviews are approving.
• All required CI checks are green.
• The PR title meets the project's style.

Maintainers only — no force-pushes to main, no merging your own PR without an approving CODEOWNER.

Working with proto changes

When a server-internal proto changes, the in-tree generation handles it:

# Edit proto/internal/temporal/server/api/yourservice/v1/yourservice.proto
make proto

When a public API proto changes (i.e. the temporal.api.* definitions in go.temporal.io/api), follow the cross-repo dance in CONTRIBUTING.md: set replace directives in go.mod to point at your local checkout, run make proto && make bins, and submit PRs in temporalio/api, temporalio/api-go, and this repo together.

Releases

Releases are cut by maintainers from main. The release workflow at .github/workflows/release.yml tags a new version, builds binaries, and updates Helm charts in adjacent repositories. Contributors do not need to do anything special — your merged PR will be in the next release after it lands.

See also Tooling for code generation details and Testing for coverage expectations.