ci: introduce towncrier to generate changelog from fragments (#4573)

* introduce towncrier to generate changelog from fragments

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.

Root .changelog/ is used for coordinated releases (most packages).
Per-package .changelog/ dirs are used for independently released packages
(opamp-client, propagator-aws-xray, resource-detector-azure, sdk-extension-aws).

Changes:
- Add towncrier config to root pyproject.toml and 4 independent package
  pyproject.toml files
- Add shared Jinja2 template at scripts/changelog_template.j2
- Replace sed-based changelog generation with towncrier build in all
  release workflows (coordinated + per-package)
- Rewrite changelog CI to use towncrier check for fragment validation
- Add do-not-edit comments and towncrier markers to all CHANGELOG.md files
- Update CONTRIBUTING.md with changelog fragment guidance
- Update RELEASING.md to reflect towncrier workflow
- Add towncrier to dev dependencies

Assisted-by: Claude Opus 4.6

* address review: drop towncrier explanation, add changelog backport

- Remove towncrier explanation sentence from RELEASING.md (per @xrmx)
- Add changelog backport step to prepare-patch-release.yml to sync
  changelog from release branch to main (per @emdneto, matching core)

Assisted-by: Claude Opus 4.6

---------

Co-authored-by: Aaron Abbott <aaronabbott@google.com>

Author: MikeGoldsmith

.changelog/.gitignore

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

.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 a .changelog/ directory. If a changelog entry
+# is not required, add the "Skip Changelog" label to disable this action.
 
 name: changelog
 
@@ -22,18 +22,46 @@ 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 files should not be directly modified."
+            echo "Please add a changelog fragment file to the appropriate .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
+        run: |
+          # Check for any new fragment files in any .changelog/ directory
+          fragments=$(git diff --diff-filter=A --name-only FETCH_HEAD -- '**/.changelog/*' '.changelog/*' | grep -v '.gitignore' || true)
+          if [[ -z "$fragments" ]]; then
+            echo "No changelog fragment found for this PR."
+            echo ""
+            echo "Add a file named .changelog/${{ github.event.pull_request.number }}.<type>"
+            echo "where <type> is one of: added, changed, deprecated, removed, fixed"
+            echo ""
+            echo "For coordinated packages, add to the root .changelog/ directory."
+            echo "For independently released packages, add to <package>/.changelog/"
+            echo "See CONTRIBUTING.md for details."
+            echo ""
+            echo "Or add the \"Skip Changelog\" label if this job should be skipped."
+            exit 1
+          fi
+          echo "Found changelog fragment(s):"
+          echo "$fragments"
+
+      - name: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - name: Preview changelog
+        run: towncrier build --draft --version Unreleased

.github/workflows/package-prepare-patch-release.yml

@@ -46,11 +46,6 @@ jobs:
             exit 1
           fi
 
-          if ! grep --quiet "^## Unreleased$" CHANGELOG.md; then
-            echo the $changelog is missing an \"Unreleased\" section
-            exit 1
-          fi
-
           version=$(./scripts/eachdist.py version --package ${{ inputs.package }})
 
           version_file=$(find $path -type f -path "**/version.py")
@@ -106,11 +101,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - name: Update the change log with the approximate release date
-        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 ${NEXT_VERSION} ($date)/" ${CHANGELOG}
+      - name: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - name: Generate changelog
+        run: towncrier build --yes --version "$NEXT_VERSION" --dir "$(dirname $CHANGELOG)"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh

.github/workflows/package-prepare-release.yml

@@ -53,11 +53,6 @@ jobs:
             exit 1
           fi
 
-          if ! grep --quiet "^## Unreleased$" $changelog; then
-            echo the $changelog is missing an \"Unreleased\" section
-            exit 1
-          fi
-
           version_dev=$(./scripts/eachdist.py version --package ${{ inputs.package }})
 
           if [[ ! $version_dev =~ ^([0-9]+)\.([0-9]+)[\.|b]{1}([0-9]+).*.dev$ ]]; then
@@ -134,10 +129,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - name: Update the change log with the approximate release date
-        run: |
-          date=$(date "+%Y-%m-%d")
-          sed -Ei "s/^## Unreleased$/## Version ${VERSION} ($date)/" ${CHANGELOG}
+      - name: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - name: Generate changelog
+        run: towncrier build --yes --version "$VERSION" --dir "$(dirname $CHANGELOG)"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh
@@ -194,11 +190,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - 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 ${VERSION} ($date)/" ${CHANGELOG}
+      - name: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - name: Generate changelog
+        run: towncrier build --yes --version "$VERSION" --dir "$(dirname $CHANGELOG)"
 
       - name: Use CLA approved github bot
         run: .github/scripts/use-cla-approved-github-bot.sh

.github/workflows/prepare-patch-release.yml

@@ -20,11 +20,6 @@ jobs:
             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)
@@ -68,10 +63,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - 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: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - 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
@@ -105,3 +101,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

.github/workflows/prepare-release-branch.yml

@@ -24,11 +24,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/}
@@ -91,10 +86,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - 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: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - 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
@@ -193,11 +189,11 @@ jobs:
       - name: run tox
         run: tox -e generate
 
-      - 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: Install towncrier
+        run: pip install towncrier==25.8.0
+
+      - 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

CHANGELOG.md

@@ -2,13 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+<!--
+Do *NOT* add changelog entries here!
+
+This changelog is managed by towncrier and is compiled at release time.
+
+See https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/CONTRIBUTING.md#changelog for details.
+-->
+
 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).
 
 > [!NOTE]
 > The following components are released independently and maintain individual CHANGELOG files.
 > Use [this search for a list of all CHANGELOG.md files in this repo](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-python-contrib+path%3A**%2FCHANGELOG.md&type=code).
 
+<!-- changelog start -->
+
 ## Unreleased
 
 ### Added

CONTRIBUTING.md

@@ -247,10 +247,46 @@ A PR is considered to be **ready to merge** when:
   reasonable time to review.
 * Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
 * Urgent fix can take exception as long as it has been actively communicated.
-* A changelog entry is added to the corresponding changelog for the code base, if there is any impact on behavior. e.g. doc entries are not required, but small bug entries are.
+* A changelog fragment is added (see [Changelog](#changelog) below), if there is any impact on behavior. e.g. doc entries are not required, but small bug entries are.
 
 Any Approver / Maintainer can merge the PR once it is **ready to merge**.
 
+### Changelog
+
+This project uses [towncrier](https://towncrier.readthedocs.io/) to manage changelogs. Instead of editing `CHANGELOG.md` directly, each PR should include a changelog fragment file.
+
+**Where to add fragments:**
+
+- **Coordinated packages** (most instrumentations, exporters, propagators): add to the root `.changelog/` directory
+- **Independently released packages** (`opentelemetry-opamp-client`, `opentelemetry-propagator-aws-xray`, `opentelemetry-resource-detector-azure`, `opentelemetry-sdk-extension-aws`): add to `<package>/.changelog/`
+
+**Creating a changelog fragment:**
+
+Create a file named `.changelog/<PR_NUMBER>.<TYPE>` where `TYPE` is one of: `added`, `changed`, `deprecated`, `removed`, `fixed`.
+
+The file should contain a one-line description of the change. For example, `.changelog/1234.fixed`:
+
+```
+`opentelemetry-instrumentation-flask`: fix request hook not being called for websocket connections
+```
+
+**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 (e.g. `` `opentelemetry-instrumentation-flask`: ... ``)
+- Don't include the PR number — towncrier adds it automatically
+
+**Preview the changelog:**
+
+```console
+towncrier build --draft --version Unreleased
+```
+
+The CI will verify that a changelog fragment exists and that `CHANGELOG.md` files are not directly modified.
+
+If your change does not need a changelog entry, add the "Skip Changelog" label to the PR.
+
 ### Stale PRs
 
 PRs with no activity for 14 days will be automatically marked as stale and closed after a further 14 days of inactivity. To prevent a PR from being marked stale, ensure there is regular activity (commits, comments, reviews, etc).

RELEASING.md

@@ -46,11 +46,7 @@ To keep the process lightweight, it's OK to approve the PRs you generate and mer
 
 ### Backporting
 
-Creating manual backports of pull request(s) requires the `backport` label to be added in order to have a green CI. Even if there where
-no changes on a repo the patch release preparation workflow requires an empty `## Unreleased` header in `CHANGELOG.md`.
-
-Backport of pull request(s) can be automated by a workflow only if there where no changes that will create conflicts in the release
-branch, unfortunately every `CHANGELOG.md` change will create one.
+Creating manual backports of pull request(s) requires the `backport` label to be added in order to have a green CI.
 
 To use the workflow to backport pull request(s) to the release branch:
   * Run the [Backport workflow](https://github.com/open-telemetry/opentelemetry-python-contrib/actions/workflows/backport.yml).
@@ -60,8 +56,6 @@ To use the workflow to backport pull request(s) to the release branch:
   * Add the label `backport` to the generated pull request.
   * In case label automation doesn't work, just close and reopen the PR so that the workflow will take into account the label automation we have in place.
   * Review and merge the backport pull request that it generates.
-* Merge a pull request to the release branch updating the `CHANGELOG.md`.
-  * The heading for the unreleased entries should be `## Unreleased`.
 
 ### Preparing a patch release
 

opamp/opentelemetry-opamp-client/.changelog/.gitignore

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