From 248c6b67f3db3a668be0720d3484ebc5fe839970 Mon Sep 17 00:00:00 2001 From: Bryan Naegele Date: Sat, 11 Jul 2026 20:03:27 -0600 Subject: [PATCH 1/3] chore: add AGENTS.md for AI coding agent guidance Documents the multi-app rebar3/mix layout, per-app build/test/lint commands, PR title conventions, and other repo-specific context AI agents need to work effectively here. Assisted-by: Claude Sonnet 5 --- AGENTS.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 121 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..9627b7ac --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,120 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. + +## What this is + +OpenTelemetry SDK/API implementation for Erlang and Elixir. It's a multi-app +rebar3 project (not a single OTP app) — each directory under `apps/` is an +independent, separately-versioned, separately-released Hex/rebar package: + +- `opentelemetry` — the SDK +- `opentelemetry_api` — the API, the main entry point for Elixir users +- `opentelemetry_api_experimental` / `opentelemetry_experimental` — experimental + API/SDK surface (metrics, logs) not yet stable +- `opentelemetry_exporter` — OTLP exporter +- `opentelemetry_zipkin` — Zipkin exporter +- `opentelemetry_semantic_conventions` — generated semantic convention constants + +`opentelemetry_api`, `opentelemetry_api_experimental`, and +`opentelemetry_semantic_conventions` are dual-published to Hex for both +rebar3 and mix, so each of those three also has its own `mix.exs`. + +Changes are usually scoped to one `apps/*` directory. Check which app(s) a +change touches before assuming a repo-wide build/test is needed. + +The OpenTelemety Specification is hosted at https://github.com/open-telemetry/opentelemetry-specification. + +The currently supported specification version is `1.8.0`. + + +## Build + +``` +rebar3 compile +``` + +Elixir-side deps (only needed for `opentelemetry_api` mix tests): + +``` +cd apps/opentelemetry_api && mix deps.get +``` + +## Tests + +The top-level `rebar.config`/`mix.exs` exist purely to run cross-app +integration tests — they are not where per-app test suites live. Each +`apps/` directory has its own `rebar.config` and is its own rebar3 +project; run Erlang test suites from inside that directory, not from the +repo root. + +- Erlang tests (per app, Common Test): `cd apps/ && rebar3 ct` + - Logs: `apps//_build/test/logs/index.html` +- Elixir tests for `opentelemetry_api`: `cd apps/opentelemetry_api && mix test` +- Top-level Elixir tests (repo-root integration tests, exercise the SDK from + Elixir): `mix test --no-start test/otel_tests.exs test/otel_metric_tests.exs` + (requires `rebar3 as test compile` from the repo root first) + +Integration tests assume backing services are up: `docker compose up -d` +(starts a collector used by exporter tests). + +## Lint / static analysis + +Run these scoped to the app you changed, from inside `apps/`: + +- `rebar3 xref` +- `rebar3 as dialyzer dialyzer` (Erlang) +- eqWAlizer (optional, requires the `elp` binary): `elp eqwalize-all` + +For `opentelemetry_api` (Elixir): + +- `mix dialyzer` +- `mix format --check-formatted` (run `mix format` without + `--check-formatted` to fix) + +CI runs these per-app on OTP 26/27/28 and Elixir 1.14/1.18 matrices — see +`.github/workflows/erlang.yml` and `.github/workflows/elixir.yml`. + +The only officially supported OTP and Elixir versions are those listed in the +CI matrices. The lowest version of each **must** be supported; never use new language +features which are unsupported in those versions. + +## Commit / PR conventions + +- PR titles **must** follow Conventional Commits using only these types: + `feat`, `fix`, `chore` (enforced by CI title-lint from `.commit-me.json`). + Titles with other types (e.g. `docs`, `refactor`, `test`) fail CI. +- Changelogs per app are generated via `git cliff` (`justfile`, `cliff.toml`) + — don't hand-edit `apps/*/CHANGELOG.md`. + +### 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. 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.5 + +## Notes for agents + +- This is a mono-repo of independently versioned, independently published + packages: a PR should generally touch a single `apps/*` directory. +- Each app's `rebar.config` declares sibling deps (e.g. `opentelemetry_api`) + by Hex version constraint, not local path. Testing an app from inside its + own directory therefore resolves those siblings from Hex (the published + version), not from your working tree — this is intentional, since it's + what real downstream users depend on. Only override a sibling dep to the + local filesystem path if a change genuinely spans apps and you need to + verify them together. If you do this, be sure to revert that override + before committing. +- `opentelemetry_experimental` / `opentelemetry_api_experimental` are unstable + by design (metrics/logs); don't "stabilize" APIs there unless asked. +- `opentelemetry_semantic_conventions` is generated code — check + `apps/opentelemetry_semantic_conventions/makefile` before hand-editing + generated modules. It uses `weaver` to codegen so any change you may want to make + is likely a change needed to the templates, instead. +- Follow the existing formatting/style in the file you're editing; don't + run repo-wide reformatting as a side effect of an unrelated change. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From bb0649009fb2bcc6e86cee23f5e237399277b337 Mon Sep 17 00:00:00 2001 From: Bryan Naegele Date: Sat, 11 Jul 2026 20:16:11 -0600 Subject: [PATCH 2/3] docs: clarify Assisted-by trailer applies to PR summaries too --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9627b7ac..7b9984b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,7 +91,7 @@ features which are unsupported in those versions. We appreciate it if users disclose the use of AI tools when the significant part of a commit is taken from a tool. When making a commit this should be disclosed through an -Assisted-by: commit message trailer. +Assisted-by: commit message trailer and as a trailer in PR Summaries. Examples: From 4eaa2c108d05726a8032825c13c9c421807d9d87 Mon Sep 17 00:00:00 2001 From: Bryan Naegele Date: Sat, 11 Jul 2026 21:59:58 -0600 Subject: [PATCH 3/3] chore(docs): refine agent guidance Clarify app-scoped builds, conditional Mix dependency setup, additional Mix tests, and semantic-conventions generation. Assisted-by: ChatGPT 5.2 --- AGENTS.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b9984b5..8ae2c947 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,21 +23,17 @@ rebar3 and mix, so each of those three also has its own `mix.exs`. Changes are usually scoped to one `apps/*` directory. Check which app(s) a change touches before assuming a repo-wide build/test is needed. -The OpenTelemety Specification is hosted at https://github.com/open-telemetry/opentelemetry-specification. +The OpenTelemetry Specification is hosted at https://github.com/open-telemetry/opentelemetry-specification. The currently supported specification version is `1.8.0`. ## Build -``` -rebar3 compile -``` - -Elixir-side deps (only needed for `opentelemetry_api` mix tests): +Build an app from its own directory: ``` -cd apps/opentelemetry_api && mix deps.get +cd apps/ && rebar3 compile ``` ## Tests @@ -50,7 +46,11 @@ repo root. - Erlang tests (per app, Common Test): `cd apps/ && rebar3 ct` - Logs: `apps//_build/test/logs/index.html` +- If Mix dependencies are missing or have changed, run `cd apps/ && mix deps.get` + in the relevant dual-published app. - Elixir tests for `opentelemetry_api`: `cd apps/opentelemetry_api && mix test` +- Elixir tests for `opentelemetry_api_experimental`: `cd apps/opentelemetry_api_experimental && mix test` +- Elixir tests for `opentelemetry_semantic_conventions`: `cd apps/opentelemetry_semantic_conventions && mix test` - Top-level Elixir tests (repo-root integration tests, exercise the SDK from Elixir): `mix test --no-start test/otel_tests.exs test/otel_metric_tests.exs` (requires `rebar3 as test compile` from the repo root first) @@ -114,7 +114,9 @@ Assisted-by: Claude Opus 4.5 by design (metrics/logs); don't "stabilize" APIs there unless asked. - `opentelemetry_semantic_conventions` is generated code — check `apps/opentelemetry_semantic_conventions/makefile` before hand-editing - generated modules. It uses `weaver` to codegen so any change you may want to make - is likely a change needed to the templates, instead. + generated modules. It uses `weaver` to codegen, so changes generally belong in + the templates or semantic-conventions version. To regenerate locally, run + `make setup`, `make checkout`, and `make generate` from + `apps/opentelemetry_semantic_conventions`. - Follow the existing formatting/style in the file you're editing; don't run repo-wide reformatting as a side effect of an unrelated change.