From 2f7f4082581fc2363e0458422487dfb8f0b9a7b2 Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Mon, 29 Jun 2026 09:14:38 -0700 Subject: [PATCH 1/7] Update contributing guide --- CONTRIBUTING.md | 111 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 97 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6096c5b2b..327485594 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,104 @@ -# Contributing to the Temporal Python SDK +# Contributing to Temporal SDKs -Thanks for your interest in contributing! +Thanks for your interest in contributing to Temporal SDKs. -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 PR. +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. -See the [README](README.md) for build and development instructions. +## Before You Open an Issue -## Changelog +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. -User-facing changes are recorded in [`CHANGELOG.md`](CHANGELOG.md), loosely following the -[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format. +Use GitHub issues for actionable bugs and feature work. For usage questions, help +debugging an application, or general discussion, use the +[Temporal community Slack](https://temporal.io/slack) or the support channel +available to you. -If your PR includes a user-facing change (new feature, behavior change, deprecation, breaking -change, notable bug fix, or security fix), add a short, high-level entry to the `## [Unreleased]` -section at the top of `CHANGELOG.md` under the appropriate heading: -Added, Changed, Deprecated, Breaking Changes, Fixed, or Security. +## Bug Reports -Keep entries high-level and written for users. The full commit log is appended at release time, -so internal-only changes (refactors, tests, CI, docs) don't need an entry. +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. + +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. + +## 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. + +## 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. + +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. From 4765926307f5790bee5d7d2c2636904cf303137c Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Mon, 29 Jun 2026 10:15:02 -0700 Subject: [PATCH 2/7] Mention AI-generated contributions --- CONTRIBUTING.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 327485594..f2a3e3ae5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,6 +72,18 @@ Avoid changes that make review harder without improving the contribution: * 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. + +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) From 45341df72bc5cf2473f5aeeb874df06db93a553e Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Mon, 29 Jun 2026 10:23:28 -0700 Subject: [PATCH 3/7] Add agent guidance --- AGENTS.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d57c02420 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,117 @@ +# Contributor Guidance for `sdk-python` + +This repository provides the Temporal Python SDK, including Python packages, +tests, optional integrations, and the Rust bridge used by the SDK. Use this +document as a quick reference when submitting pull requests. + +## Requirements for coding agents + +* Prefer the repo's Poe tasks over invoking underlying tools directly. Use + `poe test`, `poe lint`, `poe format`, `poe build-develop`, and + `poe bridge-lint` unless there is a specific reason to run a lower-level + command. +* If you are about to run tests, you do not need to run a build separately first + unless Rust bridge changes need a fresh editable extension. For bridge changes, + run `poe build-develop` before Python tests that import `temporalio`. +* Use targeted tests while iterating. `poe test -s -k ` is preferred for + a small behavioral change; run broader tests only when the change affects + shared behavior. +* Do not use `--log-cli-level` by default. The pytest configuration shows logs + for failed tests at the end without streaming all logs for passing tests. +* Tests that use the workflow environment may start a local Temporal dev server + and may download a test server binary on first run. Unit tests that do not use + the workflow environment do not start a server. +* Time-skipping tests are run with `poe test -s --workflow-environment + time-skipping`. Time-skipping does not work on Linux or Windows ARM. +* It is extremely important that comments explain why something is necessary, + not what the code already says. Avoid comments unless they clarify nonobvious + behavior. +* Avoid broad refactors, style churn, or unrelated cleanups in behavior changes. +* Avoid unqualified imports from `temporalio` packages except `temporalio.types`. + Relative imports are acceptable for private packages. +* Do not commit `uv.lock` or `pyproject.toml` changes created only for temporary + protobuf downgrade workflows. + +## Repo Specific Utilities + +* Poe tasks are defined in `pyproject.toml`: + * `poe build-develop` - build the Rust extension in editable debug mode. + * `poe test` - run pytest in parallel with the default workflow environment. + * `poe lint` - run import checks, formatting checks, type checks, and + docstyle. + * `poe lint-types` - run pyright, mypy, and basedpyright. + * `poe bridge-lint` - run clippy for the Rust bridge. + * `poe format` - run Ruff import sorting, Ruff formatting, and `cargo fmt` for + the bridge. + * `poe gen-protos-docker` - regenerate protobuf-related files using Docker. + * `poe gen-protos` - regenerate protobuf-related files without Docker, with + the Python/protobuf constraints documented in `README.md`. + +## Building and Testing + +The common local commands are: + +```bash +uv sync --all-extras +poe build-develop +poe lint +poe test +poe test -s --workflow-environment time-skipping +``` + +For focused iteration, prefer: + +```bash +poe test -s -k +uv run pytest tests/path/test_file.py::test_name +``` + +For release artifacts, use `uv build`. Documentation can be generated with +`poe gen-docs`. + +## Expectations for Pull Requests + +* Format and lint code before submitting when practical. +* Include tests for behavior changes. +* Update public API documentation or doc comments for public behavior changes. +* Add a high-level changelog entry for user-facing changes according to the + existing `CHANGELOG.md` convention. +* Keep commit messages short and in the imperative mood. +* Provide a clear PR description outlining what changed, why it changed, and + what validation was run. + +## Review Checklist + +Reviewers will look for: + +* CI passing, including build, lint, type checks, unit tests, and workflow + environment tests. +* Tests covering behavior changes. +* Clear and concise code following existing style. +* Public API documentation updates when behavior changes. +* No unrelated generated files, lockfile churn, or broad rewrites. + +## Where Things Are + +* `temporalio/` - Python SDK source. + * `temporalio/worker/` - worker implementation. + * `temporalio/converter/` - payload and failure conversion. + * `temporalio/testing/` - testing utilities. + * `temporalio/nexus/` - Nexus support. + * `temporalio/contrib/` - optional integrations. + * `temporalio/bridge/` - Rust bridge and generated bridge bindings. +* `tests/` - pytest suites mirroring SDK areas. +* `scripts/` - generation, documentation, and helper scripts. +* `build/apidocs/` - generated API documentation. +* `dist/` - built wheels and source distributions. +* `temporalio/bridge/target/` - Rust build output. You should not need to inspect + this directory. + +## Notes + +* The SDK supports Python 3.10 and newer. +* Generated protobuf and bridge files have specific regeneration workflows; see + `README.md` before changing them. +* The Rust bridge uses SDK Core from `temporalio/bridge/sdk-core`. +* `__pycache__`, `build`, `dist`, and Rust `target` outputs are generated + artifacts and should not be reviewed as source changes. From 239769904ee213858807fc54e4dea062ee27c3a5 Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Thu, 2 Jul 2026 10:42:39 -0700 Subject: [PATCH 4/7] Small updates --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2a3e3ae5..eaa90d890 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,8 +13,9 @@ feature request, or design topic, add any relevant details there instead of open duplicate. Use an upvote on the issue to show that it affects you too. Use GitHub issues for actionable bugs and feature work. For usage questions, help -debugging an application, or general discussion, use the -[Temporal community Slack](https://temporal.io/slack) or the support channel +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 @@ -42,9 +43,9 @@ 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. -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. +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. @@ -98,7 +99,8 @@ to security@temporal.io instead. 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. +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 From e05c055f4623bc8816eda98b906affab41749e05 Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Thu, 2 Jul 2026 12:02:30 -0700 Subject: [PATCH 5/7] Update AGENTS.md Co-authored-by: Spencer Judge --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d57c02420..89bf90bcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ document as a quick reference when submitting pull requests. and may download a test server binary on first run. Unit tests that do not use the workflow environment do not start a server. * Time-skipping tests are run with `poe test -s --workflow-environment - time-skipping`. Time-skipping does not work on Linux or Windows ARM. + time-skipping`. Time-skipping does not work on Linux ARM or Windows ARM. * It is extremely important that comments explain why something is necessary, not what the code already says. Avoid comments unless they clarify nonobvious behavior. From c8840f826f95f3f4655229adcb5c08db221305d8 Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Thu, 2 Jul 2026 12:02:38 -0700 Subject: [PATCH 6/7] Update AGENTS.md Co-authored-by: Spencer Judge --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 89bf90bcf..3a8c473fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -71,7 +71,7 @@ For release artifacts, use `uv build`. Documentation can be generated with ## Expectations for Pull Requests -* Format and lint code before submitting when practical. +* Format and lint code before submitting. * Include tests for behavior changes. * Update public API documentation or doc comments for public behavior changes. * Add a high-level changelog entry for user-facing changes according to the From 3e3591ae2cc352752141f9d7b7d7ae80271934d0 Mon Sep 17 00:00:00 2001 From: Tim Conley Date: Thu, 2 Jul 2026 12:03:42 -0700 Subject: [PATCH 7/7] Update AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3a8c473fb..7ecbb40d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ document as a quick reference when submitting pull requests. * Avoid unqualified imports from `temporalio` packages except `temporalio.types`. Relative imports are acceptable for private packages. * Do not commit `uv.lock` or `pyproject.toml` changes created only for temporary - protobuf downgrade workflows. + protobuf downgrade workflows. Prefer to use poe gen-protos-docker when possible. ## Repo Specific Utilities