Contributor Guidance for `sdk-core`

Contributor Guidance for

sdk-core

This repository provides a Rust workspace for the Temporal Core SDK and related crates. Use this document as your quick reference when submitting pull requests.

Where Things Are

```
core/
```
– implementation of the core SDK
```
client/
```
– clients for communicating with Temporal clusters
```
core-api/
```
– API definitions exposed by core
```
sdk/
```
– pre-alpha Rust SDK built on top of core (used mainly for tests)
```
sdk-core-protos/
```
– protobuf definitions shared across crates
```
fsm/
```
– state machine implementation and macros
```
test-utils/
```
– helpers and binaries for tests
```
tests/
```
– integration, heavy, and manual tests
```
arch_docs/
```
– architectural design documents
Contributor guide:
```
README.md
```

Repo Specific Utilities

```
.cargo/config.toml
```
defines useful cargo aliases:
- ```
cargo lint
```
  – run clippy on workspace crates
- ```
cargo test-lint
```
  – run clippy on tests
- ```
cargo integ-test
```
  – run the integration test runner
```
cargo-tokio-console.sh
```
– run any cargo command with the
```
tokio-console
```
feature
```
integ-with-otel.sh
```
– run integration tests with OpenTelemetry enabled
```
.cargo/multi-worker-manual-test
```
– helper script for spawning multiple workers during manual testing

Building and Testing

The following commands are enforced for each pull request (see

README.md

cargo build            # build all crates
cargo test             # run unit tests
cargo integ-test       # integration tests (starts ephemeral server by default)
cargo test --test heavy_tests  # load tests -- agents do not need to run this and should not

Additional checks:

cargo fmt --all        # format code
cargo clippy --all -- -D warnings  # lint

Documentation can be generated with

cargo doc

Expectations for Pull Requests

Format and lint your code before submitting.
Ensure all tests pass locally. Integration tests may require a running Temporal server or the ephemeral server started by
```
cargo integ-test
```
.
Keep commit messages short and in the imperative mood.
Provide a clear PR description outlining what changed and why.
Reviewers expect new features or fixes to include corresponding tests when applicable.

Review Checklist

Reviewers will look for:

All builds, tests, and lints passing in CI
New tests covering behavior changes
Clear and concise code following existing style (see
```
README.md
```
for error handling guidance)
Documentation updates for any public API changes

Notes

Fetch workflow histories with

cargo run --bin histfetch <workflow_id> [run_id]

(binary lives in

test-utils

Protobuf files under
```
sdk-core-protos/protos/api_upstream
```
are a git subtree; see
```
README.md
```
for update instructions.

Where Things Are

core/

– implementation of the core SDK

client/

– clients for communicating with Temporal clusters

core-api/

– API definitions exposed by core

sdk/

– pre-alpha Rust SDK built on top of core (used mainly for tests)

sdk-core-protos/

– protobuf definitions shared across crates

fsm/

– state machine implementation and macros

test-utils/

– helpers and binaries for tests

tests/

– integration, heavy, and manual tests

arch_docs/

– architectural design documents

Contributor guide:

README.md

Repo Specific Utilities

.cargo/config.toml

defines useful cargo aliases:

```
cargo lint
```
– run clippy on workspace crates
```
cargo test-lint
```
– run clippy on tests
```
cargo integ-test
```
– run the integration test runner

cargo-tokio-console.sh

– run any cargo command with the

tokio-console

feature

integ-with-otel.sh

– run integration tests with OpenTelemetry enabled

.cargo/multi-worker-manual-test

– helper script for spawning multiple workers during manual testing

Building and Testing

The following commands are enforced for each pull request (see

README.md

cargo build            # build all crates
cargo test             # run unit tests
cargo integ-test       # integration tests (starts ephemeral server by default)
cargo test --test heavy_tests  # load tests -- agents do not need to run this and should not

Additional checks:

cargo fmt --all        # format code
cargo clippy --all -- -D warnings  # lint

Documentation can be generated with

cargo doc

Expectations for Pull Requests

Format and lint your code before submitting.

Ensure all tests pass locally. Integration tests may require a running Temporal server or the ephemeral server started by

cargo integ-test

Keep commit messages short and in the imperative mood.

Provide a clear PR description outlining what changed and why.

Reviewers expect new features or fixes to include corresponding tests when applicable.

Contributor Guidance for `sdk-core`

Contributor Guidance for
`sdk-core`

Where Things Are

Repo Specific Utilities

Building and Testing

Expectations for Pull Requests

Review Checklist

Notes

Related Skills

Markdown Converter

Nano Banana Pro

1password

Contributor Guidance for
`sdk-core`

Where Things Are

Repo Specific Utilities

Building and Testing

Expectations for Pull Requests

Review Checklist

Notes