From da27672a71613ea3fe28488ddedc0134c738c8b2 Mon Sep 17 00:00:00 2001 From: Vaibhav Khamgaonkar <163758748+opensourcevk@users.noreply.github.com> Date: Wed, 11 Mar 2026 15:17:46 +0530 Subject: [PATCH 1/4] Add repository AGENTS guide --- AGENTS.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..f99daabee62 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,74 @@ +# AGENTS.md + +This repository is `opentelemetry-java`, the core Java API and SDK implementation for OpenTelemetry. + +## Scope and Layout + +- This is a large multi-module Gradle build using Kotlin DSL. +- Key top-level modules include: + - `api`, `context`, `common` + - `sdk`, `sdk-extensions` + - `exporters`, `extensions` + - `integration-tests` + - `opencensus-shim`, `opentracing-shim` + - `testing-internal`, plus several `*:testing-internal` helper modules +- Module inclusion is declared in `settings.gradle.kts`. Check there before creating new modules or assuming project paths. + +## Environment + +- Use Java 21+ for building this repository. +- Published artifacts generally target Java 8+ compatibility unless a module explicitly documents otherwise. +- On Windows, use `gradlew.bat` instead of `./gradlew`. +- Some tests require a local Docker daemon. Those tests are disabled when Docker is unavailable. + +## Build and Verification + +- Preferred baseline validation: + - `gradlew.bat check` +- Full build: + - `gradlew.bat build` +- Auto-format Java and other formatted sources: + - `gradlew.bat spotlessApply` +- Verify formatting only: + - `gradlew.bat spotlessCheck` +- If you touch a specific module, prefer targeted Gradle tasks before running the full build. +- Be aware that `check` may regenerate files under `docs/apidiffs/current_vs_latest`; include those changes if they are produced by your change. + +## Coding Conventions + +- Follow Google Java Style. Formatting is enforced by Spotless. +- Preserve Java 8 source and ABI compatibility for published artifacts unless the module is explicitly incubating/internal and the change is intentional. +- Avoid breaking public APIs. This project follows semver and maintainers expect compatibility across minor and patch releases. +- Default to non-null. Any nullable argument/member should be annotated with `@Nullable`. +- Prefer `final` for public classes when extension is not intended. +- Keep public/protected Javadoc complete and valid. +- Public API additions should normally include `@since` with the next appropriate minor version. +- Avoid synchronizing on `this` or class intrinsic locks; prefer a dedicated lock object. + +## Testing and Test Utilities + +- Add or update tests with code changes unless the change is truly docs-only or build-only. +- Do not introduce Gradle `java-test-fixtures` for internal test sharing. +- For reusable internal test helpers, follow the repository pattern of dedicated `*:testing-internal` modules. +- Keep tests targeted to the affected module where possible. + +## Documentation and Specs + +- If behavior changes or new features are added, verify alignment with the OpenTelemetry specification. +- Changes to SDK autoconfigure or configuration options should also be reflected in the relevant docs on `opentelemetry.io`. +- When editing documentation, keep changes minimal and consistent with surrounding style. + +## Build Logic and Versioning + +- Shared build logic lives in `buildSrc` and convention plugins are used heavily; inspect existing module build files before adding new configuration. +- Repository versions are derived from git tags, not hardcoded in a single version file. +- If version-derived behavior looks stale locally, fetching tags may be required: `git fetch --all --tags`. +- There is a root `generateBuildSubstitutions` task for composite-build substitution snippets. + +## Practical Guidance for Agents + +- Read the target module's `build.gradle.kts` and nearby package structure before editing. +- Match existing package naming, visibility, and module boundaries; avoid moving classes across published modules without strong justification. +- Prefer small, localized changes over broad refactors. +- When changing public API, check for ripple effects across `all`, BOM, incubator, exporters, shims, and integration tests. +- If a task may touch generated docs or API diff outputs, mention that explicitly in your summary. From bbe5faf352373e2a2d0c510dffb9047a88cd7640 Mon Sep 17 00:00:00 2001 From: Vaibhav Khamgaonkar <163758748+opensourcevk@users.noreply.github.com> Date: Thu, 12 Mar 2026 04:59:58 +0530 Subject: [PATCH 2/4] feat: readme optimized --- AGENTS.md | 82 ++++++++----------------------------------------------- 1 file changed, 12 insertions(+), 70 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f99daabee62..a55947e40f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,73 +2,15 @@ This repository is `opentelemetry-java`, the core Java API and SDK implementation for OpenTelemetry. -## Scope and Layout - -- This is a large multi-module Gradle build using Kotlin DSL. -- Key top-level modules include: - - `api`, `context`, `common` - - `sdk`, `sdk-extensions` - - `exporters`, `extensions` - - `integration-tests` - - `opencensus-shim`, `opentracing-shim` - - `testing-internal`, plus several `*:testing-internal` helper modules -- Module inclusion is declared in `settings.gradle.kts`. Check there before creating new modules or assuming project paths. - -## Environment - -- Use Java 21+ for building this repository. -- Published artifacts generally target Java 8+ compatibility unless a module explicitly documents otherwise. -- On Windows, use `gradlew.bat` instead of `./gradlew`. -- Some tests require a local Docker daemon. Those tests are disabled when Docker is unavailable. - -## Build and Verification - -- Preferred baseline validation: - - `gradlew.bat check` -- Full build: - - `gradlew.bat build` -- Auto-format Java and other formatted sources: - - `gradlew.bat spotlessApply` -- Verify formatting only: - - `gradlew.bat spotlessCheck` -- If you touch a specific module, prefer targeted Gradle tasks before running the full build. -- Be aware that `check` may regenerate files under `docs/apidiffs/current_vs_latest`; include those changes if they are produced by your change. - -## Coding Conventions - -- Follow Google Java Style. Formatting is enforced by Spotless. -- Preserve Java 8 source and ABI compatibility for published artifacts unless the module is explicitly incubating/internal and the change is intentional. -- Avoid breaking public APIs. This project follows semver and maintainers expect compatibility across minor and patch releases. -- Default to non-null. Any nullable argument/member should be annotated with `@Nullable`. -- Prefer `final` for public classes when extension is not intended. -- Keep public/protected Javadoc complete and valid. -- Public API additions should normally include `@since` with the next appropriate minor version. -- Avoid synchronizing on `this` or class intrinsic locks; prefer a dedicated lock object. - -## Testing and Test Utilities - -- Add or update tests with code changes unless the change is truly docs-only or build-only. -- Do not introduce Gradle `java-test-fixtures` for internal test sharing. -- For reusable internal test helpers, follow the repository pattern of dedicated `*:testing-internal` modules. -- Keep tests targeted to the affected module where possible. - -## Documentation and Specs - -- If behavior changes or new features are added, verify alignment with the OpenTelemetry specification. -- Changes to SDK autoconfigure or configuration options should also be reflected in the relevant docs on `opentelemetry.io`. -- When editing documentation, keep changes minimal and consistent with surrounding style. - -## Build Logic and Versioning - -- Shared build logic lives in `buildSrc` and convention plugins are used heavily; inspect existing module build files before adding new configuration. -- Repository versions are derived from git tags, not hardcoded in a single version file. -- If version-derived behavior looks stale locally, fetching tags may be required: `git fetch --all --tags`. -- There is a root `generateBuildSubstitutions` task for composite-build substitution snippets. - -## Practical Guidance for Agents - -- Read the target module's `build.gradle.kts` and nearby package structure before editing. -- Match existing package naming, visibility, and module boundaries; avoid moving classes across published modules without strong justification. -- Prefer small, localized changes over broad refactors. -- When changing public API, check for ripple effects across `all`, BOM, incubator, exporters, shims, and integration tests. -- If a task may touch generated docs or API diff outputs, mention that explicitly in your summary. +Primary contributor guidance lives in [CONTRIBUTING.md](CONTRIBUTING.md). Read that first and treat +it as the source of truth for repository layout, build and test commands, style expectations, and +scope. + +Additional guidance for agents: + +* Prefer small, localized changes over broad refactors. +* Read the target module's `build.gradle.kts` and nearby package structure before editing. +* Match existing package naming, visibility, and module boundaries. +* When changing public API, check for ripple effects across `all`, BOM, incubator, exporters, + shims, and integration tests. +* Mention generated outputs such as `docs/apidiffs/current_vs_latest` when they are affected. From 949cc78ed1b38712decf486edab40fb2b5abe2cb Mon Sep 17 00:00:00 2001 From: Vaibhav Khamgaonkar <163758748+opensourcevk@users.noreply.github.com> Date: Thu, 12 Mar 2026 11:47:03 +0530 Subject: [PATCH 3/4] docs: minimize AGENTS guidance --- AGENTS.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a55947e40f7..9ab8ec79605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,9 @@ # AGENTS.md -This repository is `opentelemetry-java`, the core Java API and SDK implementation for OpenTelemetry. - -Primary contributor guidance lives in [CONTRIBUTING.md](CONTRIBUTING.md). Read that first and treat -it as the source of truth for repository layout, build and test commands, style expectations, and -scope. +Read [CONTRIBUTING.md](CONTRIBUTING.md) first. It is the source of truth for repository layout, +build and test commands, style expectations, and scope. Additional guidance for agents: * Prefer small, localized changes over broad refactors. -* Read the target module's `build.gradle.kts` and nearby package structure before editing. -* Match existing package naming, visibility, and module boundaries. -* When changing public API, check for ripple effects across `all`, BOM, incubator, exporters, - shims, and integration tests. * Mention generated outputs such as `docs/apidiffs/current_vs_latest` when they are affected. From f7466f912a4aa6d155f5e7e0778fbf62ffe56d5f Mon Sep 17 00:00:00 2001 From: Vaibhav Khamgaonkar <163758748+opensourcevk@users.noreply.github.com> Date: Fri, 13 Mar 2026 07:30:47 +0530 Subject: [PATCH 4/4] feat: readme optimized --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9ab8ec79605..7640dfc32f1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,4 +6,3 @@ build and test commands, style expectations, and scope. Additional guidance for agents: * Prefer small, localized changes over broad refactors. -* Mention generated outputs such as `docs/apidiffs/current_vs_latest` when they are affected.