How to contribute

This section is the engineering rulebook for working in this repository. It is a wiki-friendly companion to CONTRIBUTING.md and AGENTS.md; when in doubt, the in-tree files are authoritative.

Quick map

Topic	Page
Branch / PR / merge cycle	Development workflow
Unit / integration / functional tests	Testing
Logs, common errors, troubleshooting	Debugging
Coding patterns, error handling, conventions	Patterns and conventions
Linters, code generation, CI	Tooling

Definition of done

Before opening a PR, a contributor is expected to:

1. Run the right tests for what changed. Unit tests at minimum; integration / functional tests if the change touches persistence, gRPC handlers, or workflow execution semantics. See Testing.
2. Run make lint-code and make fmt-imports. Both are enforced by CI workflows in .github/workflows/.
3. Regenerate code if any .proto file or //go:generate annotation changed. Run make proto or go generate ./<pkg>/....
4. Write a PR title that starts with an upper-case letter and has no trailing period. Enforced by the project's PR template and bots.
5. Reference the relevant issue or design doc in the PR body if the change is non-trivial. The team uses temporalio/proposals for design discussion.

Review expectations

• CODEOWNERS rules (.github/CODEOWNERS) auto-request review from the team that owns each touched directory. Common owners are:
  • @temporalio/server — broad maintainer team.
  • @temporalio/cgs — replication, NDC, multi-cluster.
  • @temporalio/oss-foundations — persistence, archiver, search attributes, scanner.
  • @temporalio/oss-matching — Matching service, task queues, worker versioning.
  • @temporalio/act — workflows-as-code, schedulers, batchers, parent-close policy.
  • @temporalio/nexus — Nexus framework and components.
• Review focuses on correctness in the presence of crashes, retries, and concurrent shard ownership transitions. Many bugs hide in non-happy-paths; reviewers will ask about them.
• Pre-commit guidance from AGENTS.md applies: comments explain why, not what; never introduce new third-party libraries without a maintainer's approval.

Where things are decided

Forum	Use it for
temporalio/proposals	Cross-cutting design proposals.
GitHub issue on this repo	Specific bugs, feature requests.
community.temporal.io	User-facing questions; rarely server-internals.
Internal Slack (Temporal Technologies employees)	Day-to-day reviews; not for external contributors.

When you get stuck

• Skim docs/architecture/ — most cross-cutting questions are answered there.
• For workflow-engine semantics, see service/history/ and the History service page.
• Open a draft PR early; reviewers prefer to discuss code over speculation.