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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6096c5b2b..f2a3e3ae5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,116 @@ -# 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. + +## 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) +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.