|
| 1 | +# Agent Instructions |
| 2 | + |
| 3 | +Guidance for AI coding agents (GitHub Copilot, Claude, Codex, Cursor, etc.) working in |
| 4 | +this repository. Human contributors should follow [CONTRIBUTING.md](CONTRIBUTING.md); |
| 5 | +this file captures the conventions an automated agent must respect to keep CI |
| 6 | +green and reviews short. |
| 7 | + |
| 8 | +## Repository Layout |
| 9 | + |
| 10 | +This is a Cargo workspace. Each top-level `opentelemetry-*` directory is a |
| 11 | +separately published crate. `opentelemetry-prometheus` is intentionally |
| 12 | +**outside** the workspace and must be linted/tested via its own manifest. |
| 13 | +See [docs/design/architecture.md](docs/design/architecture.md) for the |
| 14 | +API/SDK split and crate responsibilities. |
| 15 | + |
| 16 | +## Required Pre-Push Checks |
| 17 | + |
| 18 | +Always run these before pushing. They're cheap and catch the lint failures CI |
| 19 | +will otherwise flag. |
| 20 | + |
| 21 | +```sh |
| 22 | +# 1. Format every file in the workspace (always). |
| 23 | +cargo fmt --all |
| 24 | + |
| 25 | +# 2. Clippy on the crates you actually touched, with -Dwarnings. |
| 26 | +# Replace <crate> with the directory name (e.g. opentelemetry-sdk). |
| 27 | +cargo clippy -p <crate> --all-targets --all-features -- -Dwarnings |
| 28 | + |
| 29 | +# 3. Tests for the crates you touched. |
| 30 | +cargo test -p <crate> --all-features --lib |
| 31 | +``` |
| 32 | + |
| 33 | +For changes inside `opentelemetry-prometheus` (non-workspace), run from that |
| 34 | +directory: |
| 35 | + |
| 36 | +```sh |
| 37 | +(cd opentelemetry-prometheus && cargo clippy --all-targets --all-features -- -Dwarnings) |
| 38 | +(cd opentelemetry-prometheus && cargo test --all-features --lib) |
| 39 | +``` |
| 40 | + |
| 41 | +### When to Run the Full Precommit |
| 42 | + |
| 43 | +The full [scripts/precommit.sh](scripts/precommit.sh) runs `cargo update`, |
| 44 | +workspace-wide clippy, the full `cargo hack --each-feature` matrix, and the |
| 45 | +entire test suite. It takes a long time. Reserve it for: |
| 46 | + |
| 47 | +- Changes touching multiple crates or shared types (e.g. anything in |
| 48 | + `opentelemetry/src/`). |
| 49 | +- Public API changes, trait signature changes, or feature-flag changes. |
| 50 | +- Dependency bumps in `Cargo.toml`. |
| 51 | +- Changes to build scripts, proto definitions, or codegen. |
| 52 | +- Anything you suspect could regress feature-gated builds. |
| 53 | + |
| 54 | +For small, single-crate changes (a bug fix, a doc tweak, a benchmark, a test), |
| 55 | +the targeted commands above are sufficient — CI will catch anything missed. |
| 56 | + |
| 57 | +## Formatting and Lint Rules |
| 58 | + |
| 59 | +- `rustfmt` is enforced (`cargo fmt --all -- --check` runs in CI). Always |
| 60 | + format before committing; do not hand-format. |
| 61 | +- Clippy runs with `-Dwarnings` everywhere. A new warning fails CI. |
| 62 | +- Do not introduce `#[allow(...)]` to silence clippy without a comment |
| 63 | + explaining why. |
| 64 | + |
| 65 | +## Commit and PR Conventions |
| 66 | + |
| 67 | +- PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) |
| 68 | + (e.g. `fix(sdk): ...`, `feat(otlp): ...`, `docs: ...`). The |
| 69 | + `validate-pr-title` check enforces this. |
| 70 | +- Keep PRs focused and under ~500 lines where practical (see |
| 71 | + [CONTRIBUTING.md](CONTRIBUTING.md#pull-request-size-and-scope)). |
| 72 | +- Refactors must be in their own PR with no behavior changes. |
| 73 | +- Update the relevant crate's `CHANGELOG.md` under the `## vNext` / |
| 74 | + `## Unreleased` section for any user-visible change. |
| 75 | +- Do not commit generated files, editor settings, or unrelated whitespace |
| 76 | + changes. |
| 77 | + |
| 78 | +## Things Not to Do |
| 79 | + |
| 80 | +- Do not push directly to `open-telemetry/opentelemetry-rust`. Push to a |
| 81 | + fork and open a PR. |
| 82 | +- Do not bypass git hooks or CI checks (`--no-verify`, `[skip ci]`, etc.). |
| 83 | +- Do not hand-edit `Cargo.lock`; let `cargo` manage it. |
| 84 | +- Do not add new public API without updating the corresponding |
| 85 | + `allowed-external-types.toml` if one exists for that crate. |
| 86 | +- Do not create a markdown file to "document the changes you made" unless |
| 87 | + the user asked for it. |
| 88 | + |
| 89 | +## Useful References |
| 90 | + |
| 91 | +- [CONTRIBUTING.md](CONTRIBUTING.md) — full contributor guide |
| 92 | +- [docs/design/architecture.md](docs/design/architecture.md) — workspace and |
| 93 | + crate layout |
| 94 | +- [docs/adr/](docs/adr/) — past design decisions |
| 95 | +- [scripts/precommit.sh](scripts/precommit.sh) — full local CI mirror |
| 96 | +- [scripts/lint.sh](scripts/lint.sh) — exact clippy invocations CI runs |
| 97 | +- [scripts/test.sh](scripts/test.sh) — exact test invocations CI runs |
| 98 | +- [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification) |
| 99 | + — the source of truth for behavior across all OTel SDKs. Verify any |
| 100 | + spec-driven change against the relevant section. |
0 commit comments