ci: introduce towncrier to generate changelog from fragments#5187
Open
MikeGoldsmith wants to merge 3 commits intoopen-telemetry:mainfrom
Open
ci: introduce towncrier to generate changelog from fragments#5187MikeGoldsmith wants to merge 3 commits intoopen-telemetry:mainfrom
MikeGoldsmith wants to merge 3 commits intoopen-telemetry:mainfrom
Conversation
MikeGoldsmith
added
the
Skip Changelog
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 open-telemetry#4382 by @emdneto. Co-authored-by: Emídio Neto <9735060+emdneto@users.noreply.github.com> Assisted-by: Claude Opus 4.6
MikeGoldsmith
force-pushed
the
mike/towncrier-review
branch
from
6d7185f to
f664c36
Compare
Existing ## Unreleased entries stay in CHANGELOG.md — the towncrier marker is placed above them. Fragment migration can happen at the next release. Assisted-by: Claude Opus 4.6
- Regenerate misc.yml for new changelog/new-changelog tox envs - Update uv.lock for towncrier dependency - Apply ruff formatting to check_changelog_fragment.py Assisted-by: Claude Opus 4.6
emdneto
reviewed
May 8, 2026
Member
emdneto
left a comment
emdneto
left a comment
There was a problem hiding this comment.
Awesome. Thanks for resurrecting this 👍🏻 Left some comments
|
|
||
| lint-license-header-check | ||
| changelog | ||
| new-changelog |
Member
There was a problem hiding this comment.
can we remove this from here? then you don't need to run on CI
| - id: changelog | ||
| name: changelog fragment check | ||
| language: system | ||
| entry: python scripts/check_changelog_fragment.py |
Member
There was a problem hiding this comment.
i would avoid the pre-commit since some changes do not require changelog updates + you need the PR number in advance. i know you can check the last PR in the repo to see what the next number will be
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Replace manual
CHANGELOG.mdediting with towncrier fragment-based changelog management. Each PR adds a small text file in.changelog/instead of editing the changelog directly, eliminating merge conflicts.This supersedes #4382 (PoC by @emdneto) — builds on that foundation with updates for current
main, additional features informed by how pip, pytest, attrs, and Twisted use towncrier.Fixes #4307
Fixes #4309
What changed
Core towncrier setup:
pyproject.toml: towncrier config with 5 fragment types (added,changed,deprecated,removed,fixed)scripts/changelog_template.j2: custom Jinja2 template matching existing changelog formatCHANGELOG.md:<!-- changelog start -->marker added above existing## Unreleasedsection; existing entries preserved as-is and can be migrated to fragments at the next releaseCI & workflows:
.github/workflows/changelog.yml: usestowncrier check(per Twisted's approach) instead of grepping for CHANGELOG changes; rejects direct CHANGELOG.md edits; suggeststox -e new-changelogon failure.github/workflows/prepare-release-branch.yml:sedreplaced withtowncrier build.github/workflows/prepare-patch-release.yml: same + adds backport step to sync changelog to mainDeveloper experience:
tox -e new-changelog -- PR_NUMBER TYPE "Description"to create a fragmenttox -e changelogto preview generated changelogtox -e precommitchecks for missing fragments viascripts/check_changelog_fragment.pyCONTRIBUTING.md: changelog section with style guidanceImprovements over #4382
deprecatedandremovedcategories (original only had added/changed/fixed)towncrier check(Twisted's approach) instead of manual shell script for CI validationtowncrieradded to dev dependency groupotelbot[bot]main(original PR was months stale)Type of change
How Has This Been Tested?
towncrier build --draft --version "Unreleased"— verified fragment parsing and categorized outputtowncrier build --yes --version "1.42.0/0.63b0"— verified full build inserts into CHANGELOG.md at marker, deletes fragmentstowncrier check --compare-with upstream/main— verified branch-level fragment detectionscripts/check_changelog_fragment.pylogic for main vs feature branch casesDoes This PR Require a Contrib Repo Change?
Checklist: