introducing towncrier to generate changelog from fragments

.changelog/.gitignore

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

.changelog/4353.added

@@ -0,0 +1 @@
+Add Python 3.13 support

.changelog/4364.added

@@ -0,0 +1 @@
+Add `attributes` field in `metrics.get_meter` wrapper function

.changelog/4371.changed

@@ -0,0 +1 @@
+sdk: don't log or print warnings when the SDK has been disabled

.github/workflows/changelog.yml

@@ -13,24 +13,48 @@ on:
 jobs:
   changelog:
     runs-on: ubuntu-latest
-    if: |
-      !contains(github.event.pull_request.labels.*.name, 'Skip Changelog')
-      && github.actor != 'opentelemetrybot'
-
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@v4
+
+      - name: Fetch base branch - ${{ github.base_ref }}
+        run: git fetch origin ${{ github.base_ref }} --depth=1
 
-      - name: Check for CHANGELOG changes
+      - name: Ensure no changes to CHANGELOG.md
+        if: |
+          !contains(github.event.pull_request.labels.*.name, 'Skip Changelog')
+          && github.event.pull_request.user.login != 'opentelemetrybot'
         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 there are any changes to CHANGELOG.md, fail.
+          if [[ $(git diff --name-only FETCH_HEAD -- 'CHANGELOG.md') ]]
           then
-            echo "A CHANGELOG was modified. Looks good!"
+            echo "CHANGELOG.md should not be directly modified."
+            echo "Please add a entry file to the .changelog/ directory instead."
+            echo "See CONTRIBUTING.md for more details."
+            echo "Alternately, add the \"Skip Changelog\" label if this job should be skipped."
+            false
           else
-            echo "No CHANGELOG was modified."
-            echo "Please add a CHANGELOG entry, or add the \"Skip Changelog\" label if not required."
+            echo "CHANGELOG.md was not modified."
+          fi
+
+      - name: Ensure changelog entry addition
+        if: |
+          !contains(github.event.pull_request.labels.*.name, 'Skip Changelog')
+          && github.event.pull_request.user.login != 'opentelemetrybot'
+        run: |
+          if [[ -z $(git diff --diff-filter=A --name-only FETCH_HEAD -- './.changelog/${{ github.event.pull_request.number }}*') ]]
+          then
+            echo "No changelog entry was added to the ./.changelog/ directory."
+            echo "Please add a changelog entry file to the ./.changelog/ directory."
+            echo "See CONTRIBUTING.md for more details."
+            echo "Alternately, add the \"Skip Changelog\" label if this job should be skipped."
             false
+          else
+            echo "A changelog entry was added to the ./.changelog/ directory."
           fi
+
+      - name: Install towncrier
+        run: pip install towncrier
+
+      - name: Generate changelog
+        run: towncrier build --draft --version "Unreleased"

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

@@ -9,19 +9,14 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install toml
-        run: pip install toml
+        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)
@@ -56,10 +51,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
@@ -78,3 +71,32 @@ jobs:
                        --body "$message." \
                        --head $branch \
                        --base $GITHUB_REF_NAME
+
+      - 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:
+          # not using secrets.GITHUB_TOKEN since pull requests from that token do not run workflows
+          GITHUB_TOKEN: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }}
+        run: |
+          release_branch="opentelemetrybot/prepare-release-${STABLE_VERSION}-${UNSTABLE_VERSION}"
+          message="Backport ${STABLE_VERSION}/${UNSTABLE_VERSION} changelog"
+          body="Backport \`${STABLE_VERSION}/${UNSTABLE_VERSION}\` changelog"
+          branch="opentelemetrybot/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/}
@@ -44,8 +39,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install toml
-        run: pip install toml
+      - name: Install deps
+        run: pip install toml towncrier
 
       - name: Create release branch
         env:
@@ -82,10 +77,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
@@ -111,8 +104,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install toml
-        run: pip install toml
+      - name: Install deps
+        run: pip install toml towncrier
 
       - name: Set environment variables
         env:
@@ -160,11 +153,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

CHANGELOG.md

@@ -5,14 +5,7 @@ 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).
 
-## Unreleased
-
-- Add `attributes` field in `metrics.get_meter` wrapper function
-  ([#4364](https://github.com/open-telemetry/opentelemetry-python/pull/4364))
-- Add Python 3.13 support
-  ([#4353](https://github.com/open-telemetry/opentelemetry-python/pull/4353))
-- sdk: don't log or print warnings when the SDK has been disabled
-  ([#4371](https://github.com/open-telemetry/opentelemetry-python/pull/4371))
+<!-- changelog start -->
 
 ## Version 1.29.0/0.50b0 (2024-12-11)
 

pyproject.toml

@@ -49,3 +49,27 @@ known-third-party = [
   "opencensus",
 ]
 known-first-party = ["opentelemetry", "opentelemetry_example_app"]
+
+[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 # to wrap fragments to a line length of 79
+issue_pattern = "^(\\d+)" # to allow only PR numbers as prefix (e.g. 1234.fixed)
+
+[[tool.towncrier.type]]
+directory="changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory="added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory="fixed"
+name = "Fixed"
+showcontent = true

scripts/changelog_template.j2

@@ -0,0 +1,24 @@
+## Version {{ versiondata.version }} ({{ versiondata.date }})
+
+{% for section, _ in sections.items() %}
+{%- if section %}{{ section }}{% endif -%}
+
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section] %}
+### {{ definitions[category]['name'] }}
+
+{% for text, values in sections[section][category].items() %}
+{% if "\n  - " in text or '\n  * ' in text %}
+{%- set main_text, sub_items = text.split('\n', 1) %}
+- {{ main_text }} ({{ values|join(', ') }})
+{% if sub_items %}
+  {{- sub_items }}
+{% endif %}
+{% else %}
+- {{ text }} ({{ values|join(', ') }})
+{% endif %}
+{% endfor %}
+
+{% endfor %}
+{% endif %}
+{% endfor %}