opentelemetry-go/.github/copilot-instructions.md

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.

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.