ci: introduce towncrier for fragment-based changelog management

.github/workflows/changelog.yml

@@ -0,0 +1,95 @@
+# This action requires that any PR targeting the main branch should add a
+# changelog fragment file in a .changelog/ directory under the affected
+# package. If a changelog entry is not required, add the "Skip Changelog"
+# label to disable this action.
+
+name: changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'Skip Changelog') }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch base branch
+        run: git fetch origin ${{ github.base_ref }} --depth=1
+
+      - name: Ensure no direct changes to CHANGELOG.md
+        run: |
+          if [[ $(git diff --name-only FETCH_HEAD -- '**/CHANGELOG.md') ]]
+          then
+            echo "CHANGELOG.md files should not be directly modified."
+            echo "Please add a changelog fragment file to the affected package's .changelog/ directory instead."
+            echo "See CONTRIBUTING.md for details."
+            echo ""
+            echo "Or add the \"Skip Changelog\" label if this job should be skipped."
+            false
+          fi
+
+      - name: Check for changelog fragment
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          fragments=$(git diff --diff-filter=A --name-only FETCH_HEAD -- '**/.changelog/*' | grep -v '/\.gitignore$' || true)
+          if [[ -z "$fragments" ]]; then
+            echo "No changelog fragment found for this PR."
+            echo ""
+            echo "Add a file named <package>/.changelog/${PR_NUMBER}.<type>"
+            echo "where <type> is one of: added, changed, deprecated, removed, fixed"
+            echo ""
+            echo "See CONTRIBUTING.md for details."
+            echo ""
+            echo "Or add the \"Skip Changelog\" label if this job should be skipped."
+            exit 1
+          fi
+          invalid=()
+          while IFS= read -r f; do
+            base=$(basename "$f")
+            if [[ ! "$base" =~ ^([0-9]+)\.(added|changed|deprecated|removed|fixed)$ ]]; then
+              invalid+=("$f (expected <PR_NUMBER>.<type>; type one of added, changed, deprecated, removed, fixed)")
+              continue
+            fi
+            if [[ "${BASH_REMATCH[1]}" != "${PR_NUMBER}" ]]; then
+              invalid+=("$f (PR number ${BASH_REMATCH[1]} does not match this PR's number ${PR_NUMBER})")
+            fi
+          done <<< "$fragments"
+          if (( ${#invalid[@]} > 0 )); then
+            echo "Invalid changelog fragment(s):"
+            for msg in "${invalid[@]}"; do
+              echo "  $msg"
+            done
+            exit 1
+          fi
+          echo "Found changelog fragment(s):"
+          echo "$fragments"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - name: Preview changelogs
+        run: |
+          set -eu
+          for pkg in instrumentation/* util/opentelemetry-util-genai; do
+            [ -f "$pkg/pyproject.toml" ] || continue
+            grep -q "tool.towncrier" "$pkg/pyproject.toml" || continue
+            echo "=== $pkg ==="
+            (cd "$pkg" && towncrier build --draft --version Unreleased)
+          done

AGENTS.md

@@ -70,6 +70,19 @@ uv run tox -e typecheck
   `typing.cast(...)`, unless the referenced type is imported at runtime.
 - Whenever applicable, all code changes should have tests that actually validate the changes.
 
+## Changelog
+
+This repo uses [towncrier](https://towncrier.readthedocs.io/) to manage changelogs.
+
+- Do not edit `CHANGELOG.md` directly — the `changelog` workflow rejects PRs that do.
+- For changes with user-visible impact, add a fragment at `<package>/.changelog/<PR_NUMBER>.<type>`
+  containing a one-line description. Types: `added`, `changed`, `deprecated`, `removed`, `fixed`.
+- Don't include the PR number in the body — towncrier appends it from the filename.
+- Preview locally with `uv run tox -e changelog-preview`.
+- If the change needs no entry (pure docs or tooling), add the `Skip Changelog` label to the PR.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#4-update-the-changelog) for full details.
+
 ## Instrumentation rules
 
 Apply to packages under `instrumentation/`.

CONTRIBUTING.md

@@ -68,9 +68,33 @@ uv run tox -e typecheck
 
 ### 4. Update the changelog
 
-Add an entry to the affected package's `CHANGELOG.md` under the `Unreleased`
-section for any change with user-visible impact. Pure docs and tooling
-changes don't need an entry.
+This repo uses [towncrier](https://towncrier.readthedocs.io/) to manage
+changelogs. Each PR with user-visible impact must add a changelog fragment
+under the affected package's `.changelog/` directory rather than editing
+`CHANGELOG.md` directly.
+
+**Fragment path:** `<package>/.changelog/<PR_NUMBER>.<TYPE>`
+
+**Types:** `added`, `changed`, `deprecated`, `removed`, `fixed`.
+
+The file contains a one-line description. For example,
+`instrumentation/opentelemetry-instrumentation-anthropic/.changelog/123.fixed`:
+
+```
+fix request hook not being called when stream=True
+```
+
+Don't include the PR number in the body — towncrier appends it from the
+filename.
+
+Preview the rendered changelogs locally:
+
+```sh
+uv run tox -e changelog-preview
+```
+
+If your change doesn't need an entry (pure docs/tooling), add the
+`Skip Changelog` label to the PR.
 
 ## Keep PRs small
 

instrumentation/opentelemetry-instrumentation-anthropic/.changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

instrumentation/opentelemetry-instrumentation-anthropic/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!--
+Do *NOT* add changelog entries here!
+
+This changelog is managed by towncrier and is compiled at release time.
+
+The static "## Unreleased" section below pre-dates towncrier; its entries
+must be folded into the first towncrier-generated release manually.
+
+See https://github.com/open-telemetry/opentelemetry-python-genai/blob/main/CONTRIBUTING.md#changelog for details.
+-->
+
+<!-- changelog start -->
+
 ## Unreleased
 
 - Update `opentelemetry-util-genai` dependency range to `>= 0.4b0.dev, <0.5b0`

instrumentation/opentelemetry-instrumentation-anthropic/pyproject.toml

@@ -52,3 +52,37 @@ packages = ["src/opentelemetry"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.towncrier]
+directory = ".changelog"
+filename = "CHANGELOG.md"
+start_string = "<!-- changelog start -->\n"
+template = "../../scripts/changelog_template.j2"
+issue_format = "[#{issue}](https://github.com/open-telemetry/opentelemetry-python-genai/pull/{issue})"
+wrap = true
+issue_pattern = "^(\\d+)"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true

instrumentation/opentelemetry-instrumentation-claude-agent-sdk/.changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

instrumentation/opentelemetry-instrumentation-claude-agent-sdk/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!--
+Do *NOT* add changelog entries here!
+
+This changelog is managed by towncrier and is compiled at release time.
+
+The static "## Unreleased" section below pre-dates towncrier; its entries
+must be folded into the first towncrier-generated release manually.
+
+See https://github.com/open-telemetry/opentelemetry-python-genai/blob/main/CONTRIBUTING.md#changelog for details.
+-->
+
+<!-- changelog start -->
+
 ## Unreleased
 
 - Update `opentelemetry-util-genai` dependency range to `>= 0.4b0.dev, <0.5b0`

instrumentation/opentelemetry-instrumentation-claude-agent-sdk/pyproject.toml

@@ -51,3 +51,37 @@ packages = ["src/opentelemetry"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.towncrier]
+directory = ".changelog"
+filename = "CHANGELOG.md"
+start_string = "<!-- changelog start -->\n"
+template = "../../scripts/changelog_template.j2"
+issue_format = "[#{issue}](https://github.com/open-telemetry/opentelemetry-python-genai/pull/{issue})"
+wrap = true
+issue_pattern = "^(\\d+)"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true

instrumentation/opentelemetry-instrumentation-google-genai/.changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

instrumentation/opentelemetry-instrumentation-google-genai/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!--
+Do *NOT* add changelog entries here!
+
+This changelog is managed by towncrier and is compiled at release time.
+
+The static "## Unreleased" section below pre-dates towncrier; its entries
+must be folded into the first towncrier-generated release manually.
+
+See https://github.com/open-telemetry/opentelemetry-python-genai/blob/main/CONTRIBUTING.md#changelog for details.
+-->
+
+<!-- changelog start -->
+
 ## Unreleased
 
 -Add `gen_ai.usage.reasoning.output_tokens` attribute to capture thinking tokens on spans/events when the experimental sem conv flag is set. Add thinking tokens to output tokens. ([#4313](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4313))

instrumentation/opentelemetry-instrumentation-google-genai/pyproject.toml

@@ -71,3 +71,37 @@ stubPath = "types"
 reportMissingImports = "error"
 reportMissingTypeStubs = false
 pythonVersion = "3.10"
+
+[tool.towncrier]
+directory = ".changelog"
+filename = "CHANGELOG.md"
+start_string = "<!-- changelog start -->\n"
+template = "../../scripts/changelog_template.j2"
+issue_format = "[#{issue}](https://github.com/open-telemetry/opentelemetry-python-genai/pull/{issue})"
+wrap = true
+issue_pattern = "^(\\d+)"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true

instrumentation/opentelemetry-instrumentation-langchain/.changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

instrumentation/opentelemetry-instrumentation-langchain/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+<!--
+Do *NOT* add changelog entries here!
+
+This changelog is managed by towncrier and is compiled at release time.
+
+The static "## Unreleased" section below pre-dates towncrier; its entries
+must be folded into the first towncrier-generated release manually.
+
+See https://github.com/open-telemetry/opentelemetry-python-genai/blob/main/CONTRIBUTING.md#changelog for details.
+-->
+
+<!-- changelog start -->
+
 ## Unreleased
 
 - Fix compatibility with wrapt 2.x by using positional arguments in `wrap_function_wrapper()` calls

instrumentation/opentelemetry-instrumentation-langchain/pyproject.toml

@@ -52,3 +52,37 @@ include = [
 [tool.hatch.build.targets.wheel]
 packages = ["src/opentelemetry"]
 
+
+[tool.towncrier]
+directory = ".changelog"
+filename = "CHANGELOG.md"
+start_string = "<!-- changelog start -->\n"
+template = "../../scripts/changelog_template.j2"
+issue_format = "[#{issue}](https://github.com/open-telemetry/opentelemetry-python-genai/pull/{issue})"
+wrap = true
+issue_pattern = "^(\\d+)"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true

instrumentation/opentelemetry-instrumentation-openai-agents-v2/.changelog/.gitignore

@@ -0,0 +1 @@
+!.gitignore