diff --git a/.github/instructions/util-genai.instructions.md b/.github/instructions/util-genai.instructions.md index 9fa9f2d37..d7535e706 100644 --- a/.github/instructions/util-genai.instructions.md +++ b/.github/instructions/util-genai.instructions.md @@ -37,6 +37,9 @@ land the semconv change first. - Do not remove or rename public objects. Deprecate first via a docstring note pointing to the replacement (not `@deprecated` — unreliable). +- The `check-util-api` CI job fails when a public object is removed or its signature changes + compared to main. When a PR does this on purpose, ask it to list which released + instrumentations it checked, in this repo and in opentelemetry-python-contrib. - Private modules and module-private objects start with `_`. - Default to internal (`_`-prefixed) unless instrumentations need it public. - Flag every `Any` in the public API (anything not under a `_`-prefixed module) — parameters, diff --git a/.github/workflows/misc.yml b/.github/workflows/misc.yml index cfa11f162..51f645f87 100644 --- a/.github/workflows/misc.yml +++ b/.github/workflows/misc.yml @@ -194,6 +194,32 @@ jobs: - name: Run dependency check run: uv run --with packaging scripts/check_deps.py + check-util-api: + name: check-util-api + runs-on: ubuntu-slim + timeout-minutes: 10 + if: | + !contains(github.event.pull_request.labels.*.name, 'Approve Public API check') + && github.event.pull_request.user.login != 'otelbot[bot]' && github.event_name == 'pull_request' + steps: + - name: Checkout repo @ SHA - ${{ github.sha }} + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # griffe needs the PR base branch available for comparison. + fetch-depth: 0 + + - name: Set up Python 3.14 + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.14" + + - name: Set up uv + uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 + + - name: Check util public API + run: uvx --with tox-uv tox -e check-util-api + license-header-check: name: license-header-check runs-on: ubuntu-slim diff --git a/AGENTS.md b/AGENTS.md index 0f57d49b7..44f6cfae8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,12 +127,20 @@ uv run tox -e py314-test-instrumentation-genai-openai-conformance # Type check (pyright) uv run tox -e typecheck + +# Check util-genai for public API breaks against main +uv run tox -e check-util-api ``` Before opening a PR, run `uv run tox -e precommit`, `uv run tox -e typecheck`, and the changed package's test envs (`-oldest` and `-latest`, plus `-conformance` if it ships scenarios) — these mirror the CI gates. +If you change `util/opentelemetry-util-genai`, also run `uv run tox -e check-util-api`. Released +instrumentations accept any util version below 2, so removing or changing a public object can +break them on import. If the break is intended, say in the PR which released instrumentations you +checked. A maintainer then adds the `Approve Public API check` label to skip the CI job. + tox reuses cached envs and won't re-resolve dependencies on its own, so pass `--recreate` (`-r`) after editing a `tests/requirements.*.txt` or a `pyproject.toml` dependency bound — otherwise the run silently uses the previously installed versions. diff --git a/dev-requirements.txt b/dev-requirements.txt index 5e5b59ede..89595d575 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -8,5 +8,6 @@ readme-renderer==46.0 bleach==6.4.0 # transient dependency for readme-renderer markupsafe>=3.0.4 codespell==2.4.3 +griffe==2.3.0 pre-commit==4.6.2 ruff==0.16.10 diff --git a/tox.ini b/tox.ini index 94bc70745..5b299837b 100644 --- a/tox.ini +++ b/tox.ini @@ -384,6 +384,13 @@ deps = commands = python {toxinidir}/scripts/check_deps.py +[testenv:check-util-api] +description = Fail on breaking changes to the opentelemetry-util-genai public API vs the PR base branch (main locally). +deps = + -c {toxinidir}/dev-requirements.txt + griffe +commands = + griffe check opentelemetry.util.genai -s util/opentelemetry-util-genai/src -a origin/{env:GITHUB_BASE_REF:main} [testenv:changelog-preview] description = Render a draft changelog for every package that uses towncrier.