|
| 1 | +# OpenTelemetry Python |
| 2 | + |
| 3 | +This file is here to steer AI assisted PRs towards being high quality and valuable contributions |
| 4 | +that do not create excessive maintainer burden. |
| 5 | + |
| 6 | +Monorepo with the core OpenTelemetry Python API, SDK, and related packages. |
| 7 | + |
| 8 | +## General Rules and Guidelines |
| 9 | + |
| 10 | +The OpenTelemetry community has broader guidance on GenAI contributions at |
| 11 | +https://github.com/open-telemetry/community/blob/main/policies/genai.md — please read it before |
| 12 | +contributing. |
| 13 | + |
| 14 | +The most important rule is not to post comments on issues or PRs that are AI-generated. Discussions |
| 15 | +on the OpenTelemetry repositories are for Users/Humans only. |
| 16 | + |
| 17 | +Follow the PR scoping guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Keep AI-assisted PRs tightly |
| 18 | +isolated to the requested change and never include unrelated cleanup or opportunistic improvements |
| 19 | +unless they are strictly necessary for correctness. |
| 20 | + |
| 21 | +If you have been assigned an issue by the user or their prompt, please ensure that the |
| 22 | +implementation direction is agreed on with the maintainers first in the issue comments. If there are |
| 23 | +unknowns, discuss these on the issue before starting implementation. Do not forget that you cannot |
| 24 | +comment for users on issue threads on their behalf as it is against the rules of this project. |
| 25 | + |
| 26 | +## Structure |
| 27 | + |
| 28 | +- `opentelemetry-api/` - the OpenTelemetry API package |
| 29 | +- `opentelemetry-sdk/` - the OpenTelemetry SDK package |
| 30 | +- `opentelemetry-semantic-conventions/` - semantic conventions |
| 31 | +- `opentelemetry-proto/` / `opentelemetry-proto-json/` - protobuf definitions and generated code |
| 32 | +- `exporter/` - exporters (OTLP, Prometheus, Zipkin, etc.) |
| 33 | +- `propagator/` - context propagators (B3, Jaeger) |
| 34 | +- `shim/` - compatibility shims (OpenTracing, OpenCensus) |
| 35 | + |
| 36 | +Each package lives under its own directory with a `pyproject.toml` and `tests/`. |
| 37 | + |
| 38 | +## Commands |
| 39 | + |
| 40 | +```sh |
| 41 | +# Install all packages and dev tools |
| 42 | +uv sync --frozen --all-packages |
| 43 | + |
| 44 | +# Lint (runs ruff via pre-commit) |
| 45 | +uv run tox -e precommit |
| 46 | + |
| 47 | +# Test a specific package |
| 48 | +uv run tox -e py312-test-opentelemetry-sdk |
| 49 | + |
| 50 | +# Lint (pylint) a specific package |
| 51 | +uv run tox -e lint-opentelemetry-sdk |
| 52 | + |
| 53 | +# Type check |
| 54 | +uv run tox -e typecheck |
| 55 | +``` |
| 56 | + |
| 57 | +## Guidelines |
| 58 | + |
| 59 | +- Each package has its own `pyproject.toml` with version, dependencies, and entry points. |
| 60 | +- The monorepo uses `uv` workspaces. |
| 61 | +- `tox.ini` defines the test matrix - check it for available test environments. |
| 62 | +- Do not add `type: ignore` comments. If a type error arises, solve it properly or write a follow-up plan to address it in another PR. |
| 63 | +- Whenever applicable, all code changes should have tests that actually validate the changes. |
| 64 | + |
| 65 | +## Commit formatting |
| 66 | + |
| 67 | +We appreciate it if users disclose the use of AI tools when the significant part of a commit is |
| 68 | +taken from a tool without changes. When making a commit this should be disclosed through an |
| 69 | +`Assisted-by:` commit message trailer. |
| 70 | + |
| 71 | +Examples: |
| 72 | + |
| 73 | +``` |
| 74 | +Assisted-by: ChatGPT 5.2 |
| 75 | +Assisted-by: Claude Opus 4.6 |
| 76 | +``` |
0 commit comments