Skip to content

[DOC] update ABI policy docs to clarify breaking changes#4180

Merged
marcalff merged 6 commits into
open-telemetry:mainfrom
dbarker:doc_update_abi_policy
Jun 27, 2026
Merged

[DOC] update ABI policy docs to clarify breaking changes#4180
marcalff merged 6 commits into
open-telemetry:mainfrom
dbarker:doc_update_abi_policy

Conversation

@dbarker

@dbarker dbarker commented Jun 24, 2026

Copy link
Copy Markdown
Member

Fixes # (issue)

Updates the ABI policy documents to expand on allowed changes and to cover API header implementation changes that impact observable behavior (clarification based on #4174).

Changes

  • Update the policy to highlight the case where an application links to multiple instrumented libraries (where each may include API headers from different otel-cpp versions).
  • Add note and link to the stdlib doc for when building with c++ standard types.
  • Provide examples of API header changes that may be allowed in a stable version and what must target an experimental version
  • Provide example and guidance on observable behavior changes (changes to method implementations) and requires these to be targeted to the experimental ABI version due to potential ODR violations.
  • Updates the ABI version policy to point to CMake and Bazel files as the source of truth for the current stable and experimental ABI version

For significant contributions please make sure you have completed the following items:

  • CHANGELOG.md updated for non-trivial changes
  • Unit tests have been added
  • Changes in public API reviewed

@dbarker dbarker marked this pull request as ready for review June 24, 2026 18:53
@dbarker dbarker requested a review from a team as a code owner June 24, 2026 18:53
@codecov

codecov Bot commented Jun 24, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.98%. Comparing base (82a2ada) to head (a9181ba).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##             main    #4180   +/-   ##
=======================================
  Coverage   82.98%   82.98%           
=======================================
  Files         406      406           
  Lines       17264    17264           
=======================================
  Hits        14325    14325           
  Misses       2939     2939           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Comment thread docs/abi-policy.md Outdated
Comment thread docs/abi-version-policy.md Outdated
Comment thread docs/abi-policy.md Outdated
Comment thread docs/abi-policy.md Outdated

@lalitb lalitb left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM overall. Thanks for tightening the ABI guidance.

Comment thread docs/abi-policy.md Outdated
@marcalff marcalff merged commit 25479cd into open-telemetry:main Jun 27, 2026
72 of 73 checks passed
@dbarker dbarker deleted the doc_update_abi_policy branch June 27, 2026 17:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants