From f6c62152cff59e59ca6fcc2dca3f1c12154e8b15 Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Tue, 14 Apr 2026 09:04:27 +0100 Subject: [PATCH 1/3] add AGENTS.md to guide AI-assisted contributions Assisted-by: Claude Sonnet 4.6 --- AGENTS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 74 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..8190d19f82 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# OpenTelemetry Python + +This file is here to steer AI assisted PRs towards being high quality and valuable contributions +that do not create excessive maintainer burden. + +Monorepo with the core OpenTelemetry Python API, SDK, and related packages. + +## General Rules and Guidelines + +The OpenTelemetry community has broader guidance on GenAI contributions at +https://github.com/open-telemetry/community/blob/main/policies/genai.md — please read it before +contributing. + +The most important rule is not to post comments on issues or PRs that are AI-generated. Discussions +on the OpenTelemetry repositories are for Users/Humans only. + +Follow the PR scoping guidance in [CONTRIBUTING.md](CONTRIBUTING.md). Keep AI-assisted PRs tightly +isolated to the requested change and never include unrelated cleanup or opportunistic improvements +unless they are strictly necessary for correctness. + +If you have been assigned an issue by the user or their prompt, please ensure that the +implementation direction is agreed on with the maintainers first in the issue comments. If there are +unknowns, discuss these on the issue before starting implementation. Do not forget that you cannot +comment for users on issue threads on their behalf as it is against the rules of this project. + +## Structure + +- `opentelemetry-api/` - the OpenTelemetry API package +- `opentelemetry-sdk/` - the OpenTelemetry SDK package +- `opentelemetry-semantic-conventions/` - semantic conventions +- `opentelemetry-proto/` / `opentelemetry-proto-json/` - protobuf definitions and generated code +- `exporter/` - exporters (OTLP, Prometheus, Zipkin, etc.) +- `propagator/` - context propagators (B3, Jaeger) +- `shim/` - compatibility shims (OpenTracing, OpenCensus) + +Each package lives under its own directory with a `pyproject.toml` and `tests/`. + +## Commands + +```sh +# Install all packages and dev tools +uv sync --frozen --all-packages + +# Lint (runs ruff via pre-commit) +uv run pre-commit run ruff --all-files + +# Test a specific package +uv run tox -e py312-test-opentelemetry-sdk + +# Type check +uv run tox -e lint-opentelemetry-sdk +``` + +## Guidelines + +- Each package has its own `pyproject.toml` with version, dependencies, and entry points. +- The monorepo uses `uv` workspaces. +- `tox.ini` defines the test matrix - check it for available test environments. +- 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. +- Whenever applicable, all code changes should have tests that actually validate the changes. + +## Commit formatting + +We appreciate it if users disclose the use of AI tools when the significant part of a commit is +taken from a tool without changes. When making a commit this should be disclosed through an +`Assisted-by:` commit message trailer. + +Examples: + +``` +Assisted-by: ChatGPT 5.2 +Assisted-by: Claude Opus 4.6 +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..8b7cbf4f64 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See [AGENTS.md](AGENTS.md). From eaf8ddd6ecce87c64c370cc21635ce7701b70523 Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Tue, 14 Apr 2026 14:54:18 +0100 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emídio Neto <9735060+emdneto@users.noreply.github.com> --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8190d19f82..b1317ea187 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,13 +42,13 @@ Each package lives under its own directory with a `pyproject.toml` and `tests/`. uv sync --frozen --all-packages # Lint (runs ruff via pre-commit) -uv run pre-commit run ruff --all-files +uv run tox -e precommit # Test a specific package uv run tox -e py312-test-opentelemetry-sdk # Type check -uv run tox -e lint-opentelemetry-sdk +uv run tox -e typecheck ``` ## Guidelines From df53446a19e4609534bd3aafa7f7479fd2cd1f43 Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Tue, 14 Apr 2026 15:03:48 +0100 Subject: [PATCH 3/3] fix AGENTS.md lint command description Assisted-by: Claude Sonnet 4.6 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 8190d19f82..56f960e6c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,7 +47,7 @@ uv run pre-commit run ruff --all-files # Test a specific package uv run tox -e py312-test-opentelemetry-sdk -# Type check +# Lint (pylint) a specific package uv run tox -e lint-opentelemetry-sdk ```