Skip to content

Commit a557803

Browse files
tconley1428Sushisource
tconley1428
and
Sushisource
authored
Update contributing guide (#1625)
* Update contributing guide * Mention AI-generated contributions * Add agent guidance * Small updates * Update AGENTS.md Co-authored-by: Spencer Judge <sjudge@hey.com> * Update AGENTS.md Co-authored-by: Spencer Judge <sjudge@hey.com> * Update AGENTS.md * Clarify issue assignment guidance --------- Co-authored-by: Spencer Judge <sjudge@hey.com>
1 parent a854453 commit a557803

2 files changed

Lines changed: 232 additions & 14 deletions

File tree

‎AGENTS.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Contributor Guidance for `sdk-python`
2+
3+
This repository provides the Temporal Python SDK, including Python packages,
4+
tests, optional integrations, and the Rust bridge used by the SDK. Use this
5+
document as a quick reference when submitting pull requests.
6+
7+
## Requirements for coding agents
8+
9+
* Prefer the repo's Poe tasks over invoking underlying tools directly. Use
10+
`poe test`, `poe lint`, `poe format`, `poe build-develop`, and
11+
`poe bridge-lint` unless there is a specific reason to run a lower-level
12+
command.
13+
* If you are about to run tests, you do not need to run a build separately first
14+
unless Rust bridge changes need a fresh editable extension. For bridge changes,
15+
run `poe build-develop` before Python tests that import `temporalio`.
16+
* Use targeted tests while iterating. `poe test -s -k <pattern>` is preferred for
17+
a small behavioral change; run broader tests only when the change affects
18+
shared behavior.
19+
* Do not use `--log-cli-level` by default. The pytest configuration shows logs
20+
for failed tests at the end without streaming all logs for passing tests.
21+
* Tests that use the workflow environment may start a local Temporal dev server
22+
and may download a test server binary on first run. Unit tests that do not use
23+
the workflow environment do not start a server.
24+
* Time-skipping tests are run with `poe test -s --workflow-environment
25+
time-skipping`. Time-skipping does not work on Linux ARM or Windows ARM.
26+
* It is extremely important that comments explain why something is necessary,
27+
not what the code already says. Avoid comments unless they clarify nonobvious
28+
behavior.
29+
* Avoid broad refactors, style churn, or unrelated cleanups in behavior changes.
30+
* Avoid unqualified imports from `temporalio` packages except `temporalio.types`.
31+
Relative imports are acceptable for private packages.
32+
* Do not commit `uv.lock` or `pyproject.toml` changes created only for temporary
33+
protobuf downgrade workflows. Prefer to use poe gen-protos-docker when possible.
34+
35+
## Repo Specific Utilities
36+
37+
* Poe tasks are defined in `pyproject.toml`:
38+
* `poe build-develop` - build the Rust extension in editable debug mode.
39+
* `poe test` - run pytest in parallel with the default workflow environment.
40+
* `poe lint` - run import checks, formatting checks, type checks, and
41+
docstyle.
42+
* `poe lint-types` - run pyright, mypy, and basedpyright.
43+
* `poe bridge-lint` - run clippy for the Rust bridge.
44+
* `poe format` - run Ruff import sorting, Ruff formatting, and `cargo fmt` for
45+
the bridge.
46+
* `poe gen-protos-docker` - regenerate protobuf-related files using Docker.
47+
* `poe gen-protos` - regenerate protobuf-related files without Docker, with
48+
the Python/protobuf constraints documented in `README.md`.
49+
50+
## Building and Testing
51+
52+
The common local commands are:
53+
54+
```bash
55+
uv sync --all-extras
56+
poe build-develop
57+
poe lint
58+
poe test
59+
poe test -s --workflow-environment time-skipping
60+
```
61+
62+
For focused iteration, prefer:
63+
64+
```bash
65+
poe test -s -k <test_or_pattern>
66+
uv run pytest tests/path/test_file.py::test_name
67+
```
68+
69+
For release artifacts, use `uv build`. Documentation can be generated with
70+
`poe gen-docs`.
71+
72+
## Expectations for Pull Requests
73+
74+
* Format and lint code before submitting.
75+
* Include tests for behavior changes.
76+
* Update public API documentation or doc comments for public behavior changes.
77+
* Add a high-level changelog entry for user-facing changes according to the
78+
existing `CHANGELOG.md` convention.
79+
* Keep commit messages short and in the imperative mood.
80+
* Provide a clear PR description outlining what changed, why it changed, and
81+
what validation was run.
82+
83+
## Review Checklist
84+
85+
Reviewers will look for:
86+
87+
* CI passing, including build, lint, type checks, unit tests, and workflow
88+
environment tests.
89+
* Tests covering behavior changes.
90+
* Clear and concise code following existing style.
91+
* Public API documentation updates when behavior changes.
92+
* No unrelated generated files, lockfile churn, or broad rewrites.
93+
94+
## Where Things Are
95+
96+
* `temporalio/` - Python SDK source.
97+
* `temporalio/worker/` - worker implementation.
98+
* `temporalio/converter/` - payload and failure conversion.
99+
* `temporalio/testing/` - testing utilities.
100+
* `temporalio/nexus/` - Nexus support.
101+
* `temporalio/contrib/` - optional integrations.
102+
* `temporalio/bridge/` - Rust bridge and generated bridge bindings.
103+
* `tests/` - pytest suites mirroring SDK areas.
104+
* `scripts/` - generation, documentation, and helper scripts.
105+
* `build/apidocs/` - generated API documentation.
106+
* `dist/` - built wheels and source distributions.
107+
* `temporalio/bridge/target/` - Rust build output. You should not need to inspect
108+
this directory.
109+
110+
## Notes
111+
112+
* The SDK supports Python 3.10 and newer.
113+
* Generated protobuf and bridge files have specific regeneration workflows; see
114+
`README.md` before changing them.
115+
* The Rust bridge uses SDK Core from `temporalio/bridge/sdk-core`.
116+
* `__pycache__`, `build`, `dist`, and Rust `target` outputs are generated
117+
artifacts and should not be reviewed as source changes.

‎CONTRIBUTING.md‎

Lines changed: 115 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,122 @@
1-
# Contributing to the Temporal Python SDK
1+
# Contributing to Temporal SDKs
22

3-
Thanks for your interest in contributing!
3+
Thanks for your interest in contributing to Temporal SDKs.
44

5-
All contributors must complete the Temporal Contributor License Agreement (CLA) before changes
6-
can be merged. A link to the CLA will be posted in the PR.
5+
This guide describes expectations that apply across Temporal SDK repositories. Each
6+
repository may have additional local conventions, but the guidance below should help
7+
you open issues and pull requests that maintainers can evaluate efficiently.
78

8-
See the [README](README.md) for build and development instructions.
9+
## Before You Open an Issue
910

10-
## Changelog
11+
Search the existing issues first. If you find an issue that describes the same bug,
12+
feature request, or design topic, add any relevant details there instead of opening a
13+
duplicate. Use an upvote on the issue to show that it affects you too.
1114

12-
User-facing changes are recorded in [`CHANGELOG.md`](CHANGELOG.md), loosely following the
13-
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
15+
Issues are assigned to people when they are actively working on them. Before taking
16+
on an issue, check whether it is already assigned so you do not duplicate someone
17+
else's work.
1418

15-
If your PR includes a user-facing change (new feature, behavior change, deprecation, breaking
16-
change, notable bug fix, or security fix), add a short, high-level entry to the `## [Unreleased]`
17-
section at the top of `CHANGELOG.md` under the appropriate heading:
18-
Added, Changed, Deprecated, Breaking Changes, Fixed, or Security.
19+
Use GitHub issues for actionable bugs and feature work. For usage questions, help
20+
debugging an application, or general discussion, join the relevant
21+
language-specific channel in the
22+
[Temporal community Slack](https://temporal.io/slack) or use the support channel
23+
available to you.
1924

20-
Keep entries high-level and written for users. The full commit log is appended at release time,
21-
so internal-only changes (refactors, tests, CI, docs) don't need an entry.
25+
## Bug Reports
26+
27+
When reporting a bug, include enough detail for someone else to reproduce or
28+
understand the problem:
29+
30+
* A short summary of the problem.
31+
* A minimal reproduction, preferably as code that can be copied into a small
32+
project or test.
33+
* What you expected to happen and what actually happened.
34+
* The SDK version.
35+
* The language runtime version.
36+
* The operating system and architecture.
37+
* Temporal Server or Temporal Cloud details, if the issue depends on service
38+
behavior.
39+
* Logs, stack traces, workflow histories, or other diagnostics that show the
40+
failure.
41+
* Whether the behavior is a regression, and the last version where it worked if
42+
known.
43+
44+
## Feature Requests and Design Changes
45+
46+
Open or join a GitHub issue before starting substantial feature work, behavior
47+
changes, or API design changes. This gives maintainers and other SDK users a chance
48+
to discuss the approach before you invest in a larger implementation.
49+
50+
The relevant language-specific channel in Temporal community Slack is also a good
51+
place for early discussion, but important decisions should still be captured in a
52+
GitHub issue so they are visible and searchable.
53+
54+
Small bug fixes, documentation fixes, and narrowly scoped maintenance changes can go
55+
straight to a pull request.
56+
57+
## Pull Requests
58+
59+
Good pull requests are focused and easy to review:
60+
61+
* Keep each pull request scoped to one logical change.
62+
* Include tests for behavior changes.
63+
* Update public API documentation or doc comments when public behavior changes.
64+
* Add a high-level changelog entry for user-facing changes according to the
65+
repository's local changelog convention.
66+
* Describe what changed, why it changed, and what validation you ran.
67+
68+
Run the relevant local checks when practical. CI must pass before a pull request can
69+
be merged.
70+
71+
## Things to Avoid
72+
73+
Avoid changes that make review harder without improving the contribution:
74+
75+
* Unrelated refactors mixed into a behavior change.
76+
* Style-only churn.
77+
* Large feature pull requests that were not discussed first.
78+
* License, copyright, or other legal changes without maintainer discussion.
79+
80+
## AI-Generated Contributions
81+
82+
Using AI tools while contributing is acceptable. You are responsible for the
83+
correctness, quality, and maintainability of everything you submit.
84+
85+
Thoroughly self-review AI-generated code and documentation before opening a pull
86+
request. Make sure it is correct, tested where appropriate, and consistent with the
87+
style and patterns of the codebase.
88+
89+
Keep AI-assisted changes concise and scoped. Avoid verbose generated prose,
90+
unnecessary comments, or broad rewrites that make the change harder to review.
91+
92+
## Contributor License Agreement
93+
94+
All contributors must complete the Temporal Contributor License Agreement (CLA)
95+
before changes can be merged. A link to the CLA will be posted in the pull request.
96+
97+
## Security Issues
98+
99+
Do not open public GitHub issues for suspected security vulnerabilities. Report them
100+
to security@temporal.io instead.
101+
102+
## Review and CI
103+
104+
Maintainers review pull requests for correctness, compatibility, test coverage,
105+
documentation, and long-term maintainability. Review may require changes before a
106+
pull request can be merged, and it may take maintainers some time to review a
107+
contribution.
108+
109+
CI is the final validation gate. If CI fails, update the pull request or ask for help
110+
if the failure appears unrelated to your change. Some CI gates may wait for a
111+
maintainer to approve or run them.
112+
113+
## Inactive Pull Requests
114+
115+
Maintainers may close inactive pull requests after follow-up if they are no longer
116+
moving forward. If that happens, you are welcome to reopen the pull request or open a
117+
new one when you are ready to continue.
118+
119+
## Community Conduct
120+
121+
Keep discussions respectful, constructive, and focused on the work. Clear context,
122+
specific examples, and patience with review feedback help everyone move faster.

0 commit comments

Comments
 (0)