Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (78 loc) · 4.09 KB

AGENTS.md

File metadata and controls

100 lines (78 loc) · 4.09 KB
Raw

Agent Instructions

Guidance for AI coding agents (GitHub Copilot, Claude, Codex, Cursor, etc.) working in this repository. Human contributors should follow CONTRIBUTING.md; this file captures the conventions an automated agent must respect to keep CI green and reviews short.

Repository Layout

This is a Cargo workspace. Each top-level opentelemetry-* directory is a separately published crate. opentelemetry-prometheus is intentionally outside the workspace and must be linted/tested via its own manifest. See docs/design/architecture.md for the API/SDK split and crate responsibilities.

Required Pre-Push Checks

Always run these before pushing. They're cheap and catch the lint failures CI will otherwise flag.

# 1. Format every file in the workspace (always).
cargo fmt --all

# 2. Clippy on the crates you actually touched, with -Dwarnings.
#    Replace <crate> with the directory name (e.g. opentelemetry-sdk).
cargo clippy -p <crate> --all-targets --all-features -- -Dwarnings

# 3. Tests for the crates you touched.
cargo test -p <crate> --all-features --lib

For changes inside opentelemetry-prometheus (non-workspace), run from that directory:

(cd opentelemetry-prometheus && cargo clippy --all-targets --all-features -- -Dwarnings)
(cd opentelemetry-prometheus && cargo test --all-features --lib)

When to Run the Full Precommit

The full scripts/precommit.sh runs cargo update, workspace-wide clippy, the full cargo hack --each-feature matrix, and the entire test suite. It takes a long time. Reserve it for:

  • Changes touching multiple crates or shared types (e.g. anything in opentelemetry/src/).
  • Public API changes, trait signature changes, or feature-flag changes.
  • Dependency bumps in Cargo.toml.
  • Changes to build scripts, proto definitions, or codegen.
  • Anything you suspect could regress feature-gated builds.

For small, single-crate changes (a bug fix, a doc tweak, a benchmark, a test), the targeted commands above are sufficient — CI will catch anything missed.

Formatting and Lint Rules

  • rustfmt is enforced (cargo fmt --all -- --check runs in CI). Always format before committing; do not hand-format.
  • Clippy runs with -Dwarnings everywhere. A new warning fails CI.
  • Do not introduce #[allow(...)] to silence clippy without a comment explaining why.

Commit and PR Conventions

  • PR titles follow Conventional Commits (e.g. fix(sdk): ..., feat(otlp): ..., docs: ...). The validate-pr-title check enforces this.
  • Keep PRs focused and under ~500 lines where practical (see CONTRIBUTING.md).
  • Refactors must be in their own PR with no behavior changes.
  • Update the relevant crate's CHANGELOG.md under the ## vNext / ## Unreleased section for any user-visible change.
  • Do not commit generated files, editor settings, or unrelated whitespace changes.

Things Not to Do

  • Do not push directly to open-telemetry/opentelemetry-rust. Push to a fork and open a PR.
  • Do not bypass git hooks or CI checks (--no-verify, [skip ci], etc.).
  • Do not hand-edit Cargo.lock; let cargo manage it.
  • Do not add new public API without updating the corresponding allowed-external-types.toml if one exists for that crate.
  • Do not create a markdown file to "document the changes you made" unless the user asked for it.

Useful References