# Copilot instructions for opentelemetry-go

This repository is the Go implementation of OpenTelemetry. Prefer changes that preserve specification compliance, API stability, and idiomatic Go over clever abstractions or broad refactors.

## Implementation rules

- Read the package you are editing and follow its existing patterns for naming, options, error handling, comments, and tests.
- Keep public APIs backward compatible unless the task explicitly requires a breaking change.
- Follow the OpenTelemetry specification and semantic conventions. Match span, metric, log, attribute, event, resource, and instrumentation scope behavior to the spec and existing package behavior.
- Prefer idiomatic Go and the repository's established patterns over inventing new abstractions.
- Prefer minimal, surgical changes. Avoid requesting speculative flexibility, broad refactors, or unrelated cleanup when the diff can stay focused on the goal.
- Prefer designs that keep telemetry easy to use and loosely coupled. Choose sensible defaults, avoid vendor-specific APIs or behavior, and do not force unrelated components to depend on each other.
- For configurable constructors, reuse the project's usual option pattern: unexported `config` types, sealed `Option` interfaces with `apply`, and exported `With...` or `Without...` helpers.
- Be conservative on hot paths. Avoid unnecessary allocations, reflection, interface churn, blocking, global state, and high-cardinality telemetry.
- Preserve resilience and concurrency safety. Telemetry must not unexpectedly interfere with the host application; make lifecycle, synchronization, and failure-mode invariants explicit in code and tests.
- Write comments only for intent, invariants, and non-obvious constraints. Do not add comments that restate the code.
- Add or update tests for every behavior change. Add or update benchmarks for performance-sensitive changes.
- Follow [CONTRIBUTING.md Design Choices](../CONTRIBUTING.md#design-choices).

## Documentation and repository conventions

- Non-internal, non-test packages should have Go doc comments, usually in `doc.go`.
- Non-internal, non-test, non-documentation packages should also have a `README.md` with at least a title and `pkg.go.dev` badge.
- If a change is user-visible, consider whether `CHANGELOG.md`, examples, package docs, or migration notes also need updates.
