introduce towncrier to generate changelog from fragments

MikeGoldsmith · Emídio Neto · MikeGoldsmith · commit 6d7185f89bd6 · 2026-05-08T13:03:53.000+01:00
Replace manual CHANGELOG.md editing with towncrier fragment-based changelog management. Each PR adds a small text file in .changelog/ instead of editing the changelog directly, eliminating merge conflicts. Changes: - Add towncrier configuration in pyproject.toml with 5 fragment types (added, changed, deprecated, removed, fixed) - Replace sed-based changelog generation in release workflows with towncrier build - Add changelog backport step to patch release workflow - Update CI to use towncrier check for fragment validation - Add pre-commit check via scripts/check_changelog_fragment.py - Add tox environments: changelog (preview) and new-changelog (create) - Add contributor documentation in CONTRIBUTING.md - Convert existing unreleased entries to fragment files - Add custom Jinja2 template for changelog output Based on the proof-of-concept in #4382 by @emdneto. Co-authored-by: Emídio Neto <emidio@opentelemetry.io> Assisted-by: Claude Opus 4.6
diff --git a/.changelog/.gitignore b/.changelog/.gitignore
@@ -0,0 +1 @@
+!.gitignore
diff --git a/.changelog/4907.added b/.changelog/4907.added
@@ -0,0 +1 @@
+logs: add exception support to Logger emit and LogRecord attributes
diff --git a/.changelog/4917.added b/.changelog/4917.added
@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-proto-grpc`: make retryable gRPC error codes configurable for gRPC exporters
diff --git a/.changelog/4990.added b/.changelog/4990.added
@@ -0,0 +1 @@
+`opentelemetry-sdk`: Add `create_logger_provider`/`configure_logger_provider` to declarative file configuration
diff --git a/.changelog/4996.added b/.changelog/4996.added
@@ -0,0 +1 @@
+`opentelemetry-exporter-otlp-json-common`: add 'opentelemetry-exporter-otlp-json-common' package for OTLP JSON exporters
diff --git a/.changelog/5003.added b/.changelog/5003.added
@@ -0,0 +1 @@
+`opentelemetry-sdk`: Add `service` resource detector support to declarative file configuration
diff --git a/.changelog/5072.fixed b/.changelog/5072.fixed
@@ -0,0 +1 @@
+Fix incorrect code example in `create_tracer()` docstring
diff --git a/.changelog/5076.removed b/.changelog/5076.removed
@@ -0,0 +1 @@
+Drop Python 3.9 support
diff --git a/.changelog/5083.fixed b/.changelog/5083.fixed
@@ -0,0 +1 @@
+`opentelemetry-sdk`: Fix `ProcessResourceDetector` to use `sys.orig_argv`
diff --git a/.changelog/5088.added b/.changelog/5088.added
@@ -0,0 +1 @@
+Add WeaverLiveCheck test util
diff --git a/.changelog/5091.fixed b/.changelog/5091.fixed
@@ -0,0 +1 @@
+`opentelemetry-sdk`: fix YAML structure injection via environment variable substitution in declarative file configuration
diff --git a/.changelog/5093.added b/.changelog/5093.added
@@ -0,0 +1 @@
+`opentelemetry-sdk`: add `load_entry_point` shared utility to declarative file configuration for loading plugins via entry points
diff --git a/.changelog/5096.changed b/.changelog/5096.changed
@@ -0,0 +1 @@
+`opentelemetry-semantic-conventions`: use `X | Y` union annotation
diff --git a/.changelog/5119.changed b/.changelog/5119.changed
@@ -0,0 +1 @@
+`opentelemetry-api`: update `EnvironmentGetter` and `EnvironmentSetter` to use normalized environment variable names
diff --git a/.changelog/5120.fixed b/.changelog/5120.fixed
@@ -0,0 +1 @@
+`opentelemetry-sdk`: make resource detector ordering deterministic
diff --git a/.changelog/5131.added b/.changelog/5131.added
@@ -0,0 +1 @@
+`opentelemetry-sdk`: add `additional_properties` support to generated config models via custom `datamodel-codegen` template
diff --git a/.changelog/5133.changed b/.changelog/5133.changed
@@ -0,0 +1 @@
+Apply fixes for `UP` ruff rule
diff --git a/.changelog/5135.fixed b/.changelog/5135.fixed
@@ -0,0 +1 @@
+Fix incorrect type annotation on `detectors` parameter of `get_aggregated_resources`
diff --git a/.changelog/5145.changed b/.changelog/5145.changed
@@ -0,0 +1 @@
+`opentelemetry-sdk`: only load entrypoints for resource detectors if they are configured via `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS`
diff --git a/.changelog/5149.fixed b/.changelog/5149.fixed
@@ -0,0 +1 @@
+ci: wait for tracecontext server readiness instead of a fixed sleep
diff --git a/.changelog/5163.changed b/.changelog/5163.changed
@@ -0,0 +1 @@
+`opentelemetry-api`: Enforce W3C Baggage size limits on outbound propagation in `W3CBaggagePropagator.inject()`
diff --git a/.changelog/5177.changed b/.changelog/5177.changed
@@ -0,0 +1 @@
+Switch to SPDX license headers and add CI enforcement
diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml
@@ -1,6 +1,6 @@
-# This action requires that any PR targeting the main branch should touch at
-# least one CHANGELOG file. If a CHANGELOG entry is not required, add the "Skip
-# Changelog" label to disable this action.
+# This action requires that any PR targeting the main branch should add a
+# changelog fragment file in the .changelog/ directory. If a changelog entry
+# is not required, add the "Skip Changelog" label to disable this action.
 
 name: changelog
 
@@ -22,18 +22,40 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-      - name: Check for CHANGELOG changes
+      - name: Fetch base branch
+        run: git fetch origin ${{ github.base_ref }} --depth=1
+
+      - name: Ensure no direct changes to CHANGELOG.md
         run: |
-          # Only the latest commit of the feature branch is available
-          # automatically. To diff with the base branch, we need to
-          # fetch that too (and we only need its latest commit).
-          git fetch origin ${{ github.base_ref }} --depth=1
-          if [[ $(git diff --name-only FETCH_HEAD | grep CHANGELOG) ]]
+          if [[ $(git diff --name-only FETCH_HEAD -- 'CHANGELOG.md') ]]
           then
-            echo "A CHANGELOG was modified. Looks good!"
-          else
-            echo "No CHANGELOG was modified."
-            echo "Please add a CHANGELOG entry, or add the \"Skip Changelog\" label if not required."
+            echo "CHANGELOG.md should not be directly modified."
+            echo "Please add a changelog fragment file to the .changelog/ directory instead."
+            echo ""
+            echo "Create a fragment with:"
+            echo "  tox -e new-changelog -- ${{ github.event.pull_request.number }} TYPE \"Description\""
+            echo "where TYPE is one of: added, changed, deprecated, removed, fixed"
+            echo ""
+            echo "Or add the \"Skip Changelog\" label if this job should be skipped."
+            false
+          fi
+
+      - name: Install towncrier
+        run: pip install towncrier
+
+      - name: Check for changelog fragment
+        run: |
+          if ! towncrier check --compare-with origin/${{ github.base_ref }}; then
+            echo ""
+            echo "No changelog fragment found for this PR."
+            echo ""
+            echo "Create a fragment with:"
+            echo "  tox -e new-changelog -- ${{ github.event.pull_request.number }} TYPE \"Description\""
+            echo "where TYPE is one of: added, changed, deprecated, removed, fixed"
+            echo ""
+            echo "Or add the \"Skip Changelog\" label if this job should be skipped."
             false
           fi
diff --git a/.github/workflows/prepare-patch-release.yml b/.github/workflows/prepare-patch-release.yml
@@ -14,20 +14,15 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install toml
-        run: pip install toml
+      - name: Install dependencies
+        run: pip install toml towncrier
 
       - run: |
           if [[ ! $GITHUB_REF_NAME =~ ^release/v[0-9]+\.[0-9]+\.x-0\.[0-9]+bx$ ]]; then
             echo this workflow should only be run against long-term release branches
             exit 1
           fi
 
-          if ! grep --quiet "^## Unreleased$" CHANGELOG.md; then
-            echo the change log is missing an \"Unreleased\" section
-            exit 1
-          fi
-
       - name: Set environment variables
         run: |
           stable_version=$(./scripts/eachdist.py version --mode stable)
@@ -62,10 +57,8 @@ jobs:
       - name: Update version
         run: .github/scripts/update-version-patch.sh $STABLE_VERSION $UNSTABLE_VERSION $STABLE_VERSION_PREV $UNSTABLE_VERSION_PREV
 
-      - name: Update the change log with the approximate release date
-        run: |
-          date=$(date "+%Y-%m-%d")
-          sed -Ei "s/^## Unreleased$/## Version ${STABLE_VERSION}\/${UNSTABLE_VERSION} ($date)/" CHANGELOG.md
+      - name: Generate changelog
+        run: towncrier build --yes --version "$STABLE_VERSION/$UNSTABLE_VERSION"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh
@@ -99,3 +92,31 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           gh pr edit ${{ steps.create_pr.outputs.pr_url }}  --add-label "prepare-release"
+
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Use CLA approved github bot
+        run: .github/scripts/use-cla-approved-github-bot.sh
+
+      - name: Backport patch release changelog to main
+        env:
+          GITHUB_TOKEN: ${{ steps.otelbot-token.outputs.token }}
+        run: |
+          release_branch="otelbot/prepare-release-${STABLE_VERSION}-${UNSTABLE_VERSION}"
+          message="Backport ${STABLE_VERSION}/${UNSTABLE_VERSION} changelog"
+          body="Backport \`${STABLE_VERSION}/${UNSTABLE_VERSION}\` changelog"
+          branch="otelbot/backport-changelog-from-${STABLE_VERSION}-${UNSTABLE_VERSION}"
+
+          git fetch origin $release_branch
+
+          # Copy the updated CHANGELOG.md from the release branch
+          git checkout $release_branch -- CHANGELOG.md
+          git commit -m "$message"
+
+          git push origin HEAD:$branch
+          gh pr create --title "$message" \
+                       --body "$body" \
+                       --head $branch \
+                       --base main
diff --git a/.github/workflows/prepare-release-branch.yml b/.github/workflows/prepare-release-branch.yml
@@ -27,11 +27,6 @@ jobs:
             exit 1
           fi
 
-          if ! grep --quiet "^## Unreleased$" CHANGELOG.md; then
-            echo the change log is missing an \"Unreleased\" section
-            exit 1
-          fi
-
           if [[ ! -z $PRERELEASE_VERSION ]]; then
             stable_version=$(./scripts/eachdist.py version --mode stable)
             stable_version=${stable_version//.dev/}
@@ -50,8 +45,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install toml
-        run: pip install toml
+      - name: Install dependencies
+        run: pip install toml towncrier
 
       - name: Create release branch
         env:
@@ -88,10 +83,8 @@ jobs:
       - name: Update version
         run: .github/scripts/update-version.sh $STABLE_VERSION $UNSTABLE_VERSION
 
-      - name: Update the change log with the approximate release date
-        run: |
-          date=$(date "+%Y-%m-%d")
-          sed -Ei "s/^## Unreleased$/## Version ${STABLE_VERSION}\/${UNSTABLE_VERSION} ($date)/" CHANGELOG.md
+      - name: Generate changelog
+        run: towncrier build --yes --version "$STABLE_VERSION/$UNSTABLE_VERSION"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh
@@ -135,8 +128,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install toml
-        run: pip install toml
+      - name: Install dependencies
+        run: pip install toml towncrier
 
       - name: Set environment variables
         env:
@@ -184,11 +177,8 @@ jobs:
       - name: Update version
         run: .github/scripts/update-version.sh $STABLE_NEXT_VERSION $UNSTABLE_NEXT_VERSION
 
-      - name: Update the change log on main
-        run: |
-          # the actual release date on main will be updated at the end of the release workflow
-          date=$(date "+%Y-%m-%d")
-          sed -Ei "s/^## Unreleased$/## Unreleased\n\n## Version ${STABLE_VERSION}\/${UNSTABLE_VERSION} ($date)/" CHANGELOG.md
+      - name: Generate changelog
+        run: towncrier build --yes --version "$STABLE_VERSION/$UNSTABLE_VERSION"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -19,3 +19,11 @@ repos:
       - id: rstcheck
         additional_dependencies: ['rstcheck[sphinx]']
         args: ["--report-level", "warning"]
+  - repo: local
+    hooks:
+      - id: changelog
+        name: changelog fragment check
+        language: system
+        entry: python scripts/check_changelog_fragment.py
+        pass_filenames: false
+        always_run: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,50 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > [!IMPORTANT]
 > We are working on stabilizing the Log signal that would require making deprecations and breaking changes. We will try to reduce the releases that may require an update to your code, especially for instrumentations or for sdk developers.
 
-## Unreleased
-
-- Apply fixes for `UP` ruff rule
-  ([#5133](https://github.com/open-telemetry/opentelemetry-python/pull/5133))
-- Switch to SPDX license headers and add CI enforcement
-  ([#5177](https://github.com/open-telemetry/opentelemetry-python/pull/5177))
-- `opentelemetry-api`: Enforce W3C Baggage size limits on outbound propagation in `W3CBaggagePropagator.inject()`. Previously only inbound extraction enforced limits; now inject also caps entries at 180, individual pairs at 4096 bytes, and total header at 8192 bytes per the W3C Baggage spec. The extract path max_pairs limit now counts all size-valid entries rather than only successfully parsed ones.
-  ([#5163](https://github.com/open-telemetry/opentelemetry-python/pull/5163))
-- `opentelemetry-sdk`: add `additional_properties` support to generated config models via custom `datamodel-codegen` template, enabling plugin/custom component names to flow through typed dataclasses
-  ([#5131](https://github.com/open-telemetry/opentelemetry-python/pull/5131))
-- Fix incorrect code example in `create_tracer()` docstring
-  ([#5072](https://github.com/open-telemetry/opentelemetry-python/issues/5072))
-- `opentelemetry-sdk`: add `load_entry_point` shared utility to declarative file configuration for loading plugins via entry points; refactor propagator loading to use it
-  ([#5093](https://github.com/open-telemetry/opentelemetry-python/pull/5093))
-- `opentelemetry-sdk`: fix YAML structure injection via environment variable substitution in declarative file configuration; values containing newlines are now emitted as quoted YAML scalars per spec requirement
-  ([#5091](https://github.com/open-telemetry/opentelemetry-python/pull/5091))
-- `opentelemetry-sdk`: Add `create_logger_provider`/`configure_logger_provider` to declarative file configuration, enabling LoggerProvider instantiation from config files without reading env vars
-  ([#4990](https://github.com/open-telemetry/opentelemetry-python/pull/4990))
-- `opentelemetry-sdk`: Add `service` resource detector support to declarative file configuration via `detection_development.detectors[].service`
-  ([#5003](https://github.com/open-telemetry/opentelemetry-python/pull/5003))
-- logs: add exception support to Logger emit and LogRecord attributes
-  ([#4907](https://github.com/open-telemetry/opentelemetry-python/issues/4907))
-- Drop Python 3.9 support
-  ([#5076](https://github.com/open-telemetry/opentelemetry-python/pull/5076))
-- `opentelemetry-semantic-conventions`: use `X | Y` union annotation
-  ([#5096](https://github.com/open-telemetry/opentelemetry-python/pull/5096))
-- `opentelemetry-sdk`: Fix `ProcessResourceDetector` to use `sys.orig_argv` so that `process.command`, `process.command_line`, and `process.command_args` reflect the original invocation for `python -m <module>` runs (where `sys.argv[0]` is rewritten to the module path)
-  ([#5083](https://github.com/open-telemetry/opentelemetry-python/pull/5083))
-- `opentelemetry-sdk`: make resource detector ordering deterministic
-  ([#5120](https://github.com/open-telemetry/opentelemetry-python/pull/5120))
-- Add WeaverLiveCheck test util
-  ([#5088](https://github.com/open-telemetry/opentelemetry-python/pull/5088))
-- Fix incorrect type annotation on `detectors` parameter of `get_aggregated_resources`
-  ([#5135](https://github.com/open-telemetry/opentelemetry-python/pull/5135))
-- ci: wait for tracecontext server readiness instead of a fixed sleep in `scripts/tracecontext-integration-test.sh`
-  ([#5149](https://github.com/open-telemetry/opentelemetry-python/pull/5149))
-- `opentelemetry-api`: update `EnvironmentGetter` and `EnvironmentSetter` to use normalized environment variable names
-  ([#5119](https://github.com/open-telemetry/opentelemetry-python/pull/5119))
-- `opentelemetry-sdk`: only load entrypoints for resource detectors if they are configured via `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS`
-  ([#5145](https://github.com/open-telemetry/opentelemetry-python/pull/5145))
-- `opentelemetry-exporter-otlp-json-common`: add 'opentelemetry-exporter-otlp-json-common' package for OTLP JSON exporters
-  ([#4996](https://github.com/open-telemetry/opentelemetry-python/pull/4996))
-- `opentelemetry-exporter-otlp-proto-grpc`: make retryable gRPC error codes configurable for gRPC exporters
-  ([#4917](https://github.com/open-telemetry/opentelemetry-python/pull/4917))
+<!-- changelog start -->
 
 ## Version 1.41.0/0.62b0 (2026-04-09)
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -73,6 +73,45 @@ You can run `tox` with the following arguments:
 - `tox -e tracecontext` to run integration tests for tracecontext.
 - `tox -e precommit` to run all `pre-commit` actions
 
+### Changelog
+
+This project uses [towncrier](https://towncrier.readthedocs.io/) to manage the changelog. Instead of editing `CHANGELOG.md` directly, each PR should include a changelog fragment file in the `.changelog/` directory.
+
+**Creating a changelog fragment:**
+
+```console
+tox -e new-changelog -- PR_NUMBER TYPE "Description of the change"
+```
+
+Where `TYPE` is one of: `added`, `changed`, `deprecated`, `removed`, `fixed`.
+
+For example:
+
+```console
+tox -e new-changelog -- 1234 added "`opentelemetry-sdk`: add support for new feature"
+```
+
+This creates a file `.changelog/1234.added` containing the description. You can also create the file manually — it's just a text file with the description on one line.
+
+**Writing a good changelog entry:**
+
+- Write in imperative tone, as if completing the phrase "This change will..."
+- Keep entries concise — ideally under 80 characters
+- Prefix with the affected package name when applicable (e.g. `` `opentelemetry-sdk`: ... ``)
+- Don't include the PR number — towncrier adds it automatically
+
+**Preview the changelog:**
+
+```console
+tox -e changelog
+```
+
+Running `tox -e precommit` will check that a changelog fragment exists for your branch and remind you to create one if missing.
+
+The CI will also verify that a changelog fragment exists and that `CHANGELOG.md` is not directly modified.
+
+If your change does not need a changelog entry, add the "Skip Changelog" label to the PR.
+
 `ruff check` and `ruff format` are executed when `tox -e ruff` is run. We strongly recommend you to configure [pre-commit](https://pre-commit.com/) locally to run `ruff` and `rstcheck` automatically before each commit by installing it as git hooks. You just need to [install pre-commit](https://pre-commit.com/#install) in your environment:
 
 ```console
diff --git a/pyproject.toml b/pyproject.toml
@@ -165,11 +165,46 @@ target-python-version = "3.10"
 custom-template-dir = "opentelemetry-sdk/codegen"
 additional-imports = "typing.ClassVar,opentelemetry.sdk._configuration._common._additional_properties"
 
+[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/pull/{issue})"
+wrap = true # wrap fragments to 79 char line length
+issue_pattern = "^(\\d+)" # only PR numbers as fragment prefix (e.g. 1234.fixed)
+
+[[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
+
 [dependency-groups]
 dev = [
     "tox",
     "tox-uv>=1",
     "pre-commit",
     "datamodel-code-generator[http]",
     "datamodel-code-generator[ruff]",
+    "towncrier",
 ]
diff --git a/scripts/changelog_template.j2 b/scripts/changelog_template.j2
diff --git a/scripts/check_changelog_fragment.py b/scripts/check_changelog_fragment.py
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+logs: add exception support to Logger emit and LogRecord attributes`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`opentelemetry-exporter-otlp-proto-grpc`: make retryable gRPC error codes configurable for gRPC exporters
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`opentelemetry-sdk`: Add `create_logger_provider`/`configure_logger_provider` to declarative file configuration
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`opentelemetry-exporter-otlp-json-common`: add 'opentelemetry-exporter-otlp-json-common' package for OTLP JSON exporters
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`opentelemetry-sdk`: Add `service` resource detector support to declarative file configuration
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Fix incorrect code example in `create_tracer()` docstring
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+`opentelemetry-sdk`: Fix `ProcessResourceDetector` to use `sys.orig_argv`