Update contributing guide

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 <pattern>` 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 <test_or_pattern>
+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.

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.