# Contributing to Temporal SDKs Thanks for your interest in contributing to Temporal SDKs. This guide describes expectations that apply across Temporal SDK repositories. Each repository may have additional local conventions, but the guidance below should help you open issues and pull requests that maintainers can evaluate efficiently. > [!IMPORTANT] > Non-Temporal contributors must not solicit user or customer information, including but not limited to workload, use-case, or failure information. Doing so will result in a ban from all Temporal repositories at Temporal's sole discretion. ## Before You Open an Issue Search the existing issues first. If you find an issue that describes the same bug, feature request, or design topic, add any relevant details there instead of opening a duplicate. Use an upvote on the issue to show that it affects you too. Issues are assigned to people when they are actively working on them. Before taking on an issue, check whether it is already assigned so you do not duplicate someone else's work. Use GitHub issues for actionable bugs and feature work. For usage questions, help debugging an application, or general discussion, join the relevant language-specific channel in the [Temporal community Slack](https://temporal.io/slack) or use the support channel available to you. ## Bug Reports When reporting a bug, include enough detail for someone else to reproduce or understand the problem: - A short summary of the problem. - A minimal reproduction, preferably as code that can be copied into a small project or test. - What you expected to happen and what actually happened. - The SDK version. - The language runtime version. - The operating system and architecture. - Temporal Server or Temporal Cloud details, if the issue depends on service behavior. - Logs, stack traces, workflow histories, or other diagnostics that show the failure. - Whether the behavior is a regression, and the last version where it worked if known. ## Feature Requests and Design Changes Open or join a GitHub issue before starting substantial feature work, behavior changes, or API design changes. This gives maintainers and other SDK users a chance to discuss the approach before you invest in a larger implementation. The relevant language-specific channel in Temporal community Slack is also a good place for early discussion, but important decisions should still be captured in a GitHub issue so they are visible and searchable. Small bug fixes, documentation fixes, and narrowly scoped maintenance changes can go straight to a pull request. ## Pull Requests Good pull requests are focused and easy to review: - Keep each pull request scoped to one logical change. - Include tests for behavior changes. - Update public API documentation or doc comments when public behavior changes. - Add a high-level changelog entry for user-facing changes according to the repository's local changelog convention. - Describe what changed, why it changed, and what validation you ran. Run the relevant local checks when practical. CI must pass before a pull request can be merged. ## Development workflow ### Changelog fragments For user-facing changes, add a concise fragment under `changelog//` instead of editing `CHANGELOG.md`. Use fun, whimsical lowercase kebab-case names, such as `tap-dancing-teapot.md`. Each nonempty line becomes a bullet; omit the leading `-`. See [the fragment convention](changelog/README.md). Run `pnpm changelog:check` to validate pending fragments. ### Updating SDK Core Run `pnpm update-core` to update to Core's latest main commit, import its changelog entries with a `Core: ` prefix, and refresh the bridge `Cargo.lock`. Pass `--revision ` to select another locally available commit. Review and commit the pin, imported fragments, and lockfile together. Rebuild with `pnpm build`, regenerate changed protobuf definitions with `pnpm gen:protos`, and check bridge API compatibility as needed. If Cargo resolution fails, the pin and fragments remain for inspection. Updating Core no longer waits until release preparation to record its user-facing changes. ### Preparing and publishing a release From a release preparation branch, run: ```bash pnpm release:prepare 1.25.0 --date 2026-10-08 ``` The TypeScript adapter updates versioned package manifests under `packages/`, `contrib/`, and `scripts/`, refreshes `pnpm-lock.yaml`, then invokes Core's shared `prepare` command to write the dated changelog and consume fragments. The date defaults to today in UTC. Review and commit the versions, lockfile, changelog, and fragment deletions together. If preparation fails, inspect the version and lockfile changes before retrying. To assemble notes after updating versions and the lockfile manually, use `pnpm changelog:prepare --version 1.25.0 --date 2026-10-08`. Generate publishing notes with: ```bash pnpm release:notes --version 1.25.0 --output release-notes.md ``` This reads the completed changelog and appends Core commit links; it does not import entries at publish time. The shared tool selects the greatest numeric release tag below the requested version, including `v`-prefixed tags; pass `--from ` to override it. Publishing remains a maintainer operation; use this output as the GitHub Release body. The release workflow also generates a `release-notes` artifact on release branches. ## Things to Avoid Avoid changes that make review harder without improving the contribution: - Unrelated refactors mixed into a behavior change. - Style-only churn. - Large feature pull requests that were not discussed first. - License, copyright, or other legal changes without maintainer discussion. ## AI-Generated Contributions Using AI tools while contributing is acceptable. You are responsible for the correctness, quality, and maintainability of everything you submit. Contributors must fully understand theissue they are fixing and be able to explain the proposed change. We expect that human understanding to be evident in pull request responses and design discussions. If a contribution's interaction appears entirely AI-driven, maintainers may close it: it does not provide a benefit over maintainers using AI tooling themselves. Thoroughly self-review AI-generated code and documentation before opening a pull request. Make sure it is correct, tested where appropriate, and consistent with the style and patterns of the codebase. Keep AI-assisted changes concise and scoped. Avoid verbose generated prose, unnecessary comments, or broad rewrites that make the change harder to review. ## Contributor License Agreement All contributors must complete the Temporal Contributor License Agreement (CLA) before changes can be merged. A link to the CLA will be posted in the pull request. ## Security Issues Do not open public GitHub issues for suspected security vulnerabilities. Report them to security@temporal.io instead. ## Review and CI Maintainers review pull requests for correctness, compatibility, test coverage, documentation, and long-term maintainability. Review may require changes before a pull request can be merged, and it may take maintainers some time to review a contribution. CI is the final validation gate. If CI fails, update the pull request or ask for help if the failure appears unrelated to your change. Some CI gates may wait for a maintainer to approve or run them. ## Inactive Pull Requests Maintainers may close inactive pull requests after follow-up if they are no longer moving forward. If that happens, you are welcome to reopen the pull request or open a new one when you are ready to continue. ## Community Conduct Keep discussions respectful, constructive, and focused on the work. Clear context, specific examples, and patience with review feedback help everyone move faster. ## Development After your environment is set up, you can run these commands: - `pnpm build` compiles protobuf definitions, Rust bridge, C++ isolate extension, and Typescript. - `pnpm run rebuild` deletes all generated files in the project and reruns build. - `pnpm build:watch` watches filesystem for changes and incrementally compiles Typescript on change. - `pnpm test` runs the test suite. Tests assume you have a [Temporal server running locally](https://docs.temporal.io/cli#start-dev-server). - `pnpm test:watch` runs the test suite on each change to Typescript files. - `pnpm format` formats code with oxfmt. - `pnpm lint` verifies code style with oxfmt and oxlint. - `pnpm lint:prune` checks unused exports and types with Knip. - `pnpm commitlint` validates [commit messages](#style-guide). To regenerate System Nexus bindings from Core's upstream API WIT files, install the pinned nexgen release with its `advanced` feature and ensure `protoc` is on your `PATH`: ```sh cargo install nexgen --version '=0.2.11' --locked --features advanced pnpm --filter @temporalio/workflow run gen:system-nexus ``` CI uses the same release and checks that the generated bindings are up to date. Set `NEXGEN_BIN` to use a local generator build when developing nexgen changes. ### Working with Individual Packages You can build or test a single package using pnpm's filter flag: ```sh # Build a single package and all its dependencies explicitly pnpm -F @temporalio/worker... run build # Run tests for a single package pnpm -F @temporalio/common run test ``` The `...` suffix includes all dependencies of the specified package. ### Testing #### Testing local changes to core Create a `.cargo/config.toml` file and override the path to sdk-core and/or sdk-core-protos as described [here](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#paths-overrides) ##### Integration tests In order to run integration tests: 1. Run the Temporal server, e.g. using the [Temporal CLI's integrated dev server](https://github.com/temporalio/cli#start-the-server) 1. Export `RUN_INTEGRATION_TESTS=true` #### End-to-end tests The end-to-end tests (`packages/test-e2e`) install the packed `@temporalio/*` packages into fresh projects, check how npm resolves their dependencies, and run sample projects against the Temporal server already listening on `localhost:7233`. To run them locally: ``` pnpm install --frozen-lockfile pnpm run rebuild TMP_DIR=$( mktemp -d ) pnpm bridge:collect pnpm packages:pack --tarball-dir "$TMP_DIR" pnpm --filter @temporalio/test-e2e run test:e2e --tarball-dir "$TMP_DIR" rm -rf "$TMP_DIR" ``` With `--tarball-dir`, the tarballs are published to a local Verdaccio registry for the duration of the run. Without it, the packages come from the npm registry, at the version or dist-tag given by `--sdk-version`, which confirms that a published (or staged) release works. The `hello-world-mtls` sample runs against Temporal Cloud when `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, `TEMPORAL_CLIENT_CERT` and `TEMPORAL_CLIENT_KEY` are set. See `--help` for all options. The noisy output of publishing, sample creation and workers is written to `.test-results/` (or `$TEST_RESULTS_DIR`), and its tail is printed on failure. ### Style Guide - Typescript code is linted with [oxlint](https://oxc.rs/docs/guide/usage/linter.html) - Files in this repo are formatted with [oxfmt](https://oxc.rs/docs/guide/usage/formatter) - Prefer explicit named re-exports and avoid wildcard re-exports where possible (`export * from ...`) in public entrypoint / barrel files. - Use `@experimental` and `@internal` to manage API stability and visibility. Mark new or work-in-progress exported APIs `@experimental` to signal their shape may still change. Mark a symbol `@internal` to keep it out of the generated public docs. The two are independent and may be combined. It is fine to ship something `@internal` now and promote it to public later, by removing `@internal` and adding a named re-export, once it is actually usable. The reverse is a breaking change, so prefer starting narrow. - Pull request titles SHOULD adhere to the [Conventional Commits specification](https://conventionalcommits.org/), for example: ``` (optional scope): chore(samples): upgrade commander module ``` The `scope` options are listed in [commitlint.config.js](./commitlint.config.js). ## Updating and pruning dependencies There are various tools out there to help with updating and pruning NPM dependencies. I personally use the following commands to find NPM packages that needs to be updated. It runs interactively on each package of the repo, making it easy to select and apply packages to be updated. ``` for i in ./package.json packages/*/package.json contrib/*/package.json ; do ( cd "${i%%package.json}" pwd npm-check-updates -i ) done ``` To identify unused dependencies, I run the following script. Note that `npm-check` may report false-positive. Search the code before actually deleting any dependency. Also note that runtime dependencies MUST be added on the actual packages that use them to ensure proper execution in PNPM and YARN 2+ setups. ``` for i in ./package.json packages/*/package.json contrib/*/package.json ; do ( cd "${i%%package.json}" pwd npm-check ) done ``` To install both tools: `npm i -g npm-check npm-check-updates`.