ci: introduce towncrier for fragment-based changelog management#16
Merged
Merged
Conversation
Replace manual CHANGELOG.md editing with towncrier fragments. Each PR adds a small file under <package>/.changelog/ instead of editing CHANGELOG.md directly, eliminating merge conflicts on backports and concurrent PRs. Every publishable package in this repo releases independently, so each gets its own [tool.towncrier] config and .changelog/ directory. Changes: - Add [tool.towncrier] block to each package's pyproject.toml (7 instrumentations + util-genai) - Add .changelog/.gitignore stub per package - Insert do-not-edit comment and <!-- changelog start --> marker above the Unreleased header in each CHANGELOG.md - Add shared scripts/changelog_template.j2 - Add .github/workflows/changelog.yml: blocks direct CHANGELOG.md edits, requires a fragment, previews the rendered changelog per package. Skipped via the "Skip Changelog" label - Add tox -e changelog-preview for local previewing - Add towncrier to root dev dependencies - Update CONTRIBUTING.md with fragment authoring instructions Assisted-by: Claude Opus 4.7 (1M context)
- Remove changelog-preview from tox envlist so the workflow generator doesn't create a CI job for it. The env stays available for local use and the changelog.yml workflow already runs the preview in CI. - Regenerate uv.lock with the index URL form the uv-lock pre-commit hook uses (trailing slash), matching upstream. Assisted-by: Claude Opus 4.7 (1M context)
lmolkova
reviewed
May 14, 2026
lmolkova
reviewed
May 14, 2026
lmolkova
left a comment
Member
There was a problem hiding this comment.
Not sure if it's ready for review, but looks great on the first sight!
Addresses review feedback on PR open-telemetry#16 to mirror the new CONTRIBUTING.md guidance for AI-assisted contributions in a more concise form. Assisted-by: Claude Opus 4.7 (1M context)
Member
Author
|
Ready for review now - I left it in draft while I fixed up the 'Skip Changelog' label, which is working now 👍🏻 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces towncrier-based changelog management across the independently released packages in the repository, replacing direct CHANGELOG.md edits with per-package changelog fragments.
Changes:
- Adds towncrier configuration and
.changelog/directories for instrumentation packages andopentelemetry-util-genai. - Adds changelog preview support via tox, a shared towncrier template, and a new GitHub Actions changelog check.
- Updates contributor/agent documentation and root dev dependencies for the new changelog workflow.
Reviewed changes
Copilot reviewed 30 out of 31 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/changelog.yml |
Adds CI enforcement and previewing for changelog fragments. |
AGENTS.md |
Documents changelog fragment expectations for agents. |
CONTRIBUTING.md |
Replaces direct changelog instructions with towncrier fragment guidance. |
pyproject.toml |
Adds towncrier to the root dev dependency group. |
scripts/changelog_template.j2 |
Adds the shared towncrier rendering template. |
tox.ini |
Adds the changelog-preview tox environment. |
uv.lock |
Locks towncrier and its transitive dependencies. |
instrumentation/opentelemetry-instrumentation-anthropic/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-anthropic/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-anthropic/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-claude-agent-sdk/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-claude-agent-sdk/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-claude-agent-sdk/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-google-genai/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-google-genai/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-google-genai/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-langchain/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-langchain/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-langchain/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-openai-agents-v2/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-openai-agents-v2/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-openai-v2/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-openai-v2/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-openai-v2/pyproject.toml |
Adds package-specific towncrier configuration. |
instrumentation/opentelemetry-instrumentation-weaviate/CHANGELOG.md |
Adds towncrier management notice and marker. |
instrumentation/opentelemetry-instrumentation-weaviate/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
instrumentation/opentelemetry-instrumentation-weaviate/pyproject.toml |
Adds package-specific towncrier configuration. |
util/opentelemetry-util-genai/CHANGELOG.md |
Adds towncrier management notice and marker. |
util/opentelemetry-util-genai/.changelog/.gitignore |
Keeps the changelog fragment directory tracked. |
util/opentelemetry-util-genai/pyproject.toml |
Adds package-specific towncrier configuration. |
- Re-trigger the changelog workflow on labeled/unlabeled events so adding the "Skip Changelog" label without pushing a new commit is enough to clear a previously failed run. - Validate fragment basenames against <PR_NUMBER>.<type> in the workflow, catching typos in either the PR number or the fragment type before they ship a misleading changelog link. - Note in each CHANGELOG.md do-not-edit comment that the existing static "## Unreleased" entries must be folded into the first towncrier-built release manually. Assisted-by: Claude Opus 4.7 (1M context)
lmolkova
approved these changes
May 14, 2026
This was referenced May 15, 2026
MikeGoldsmith
added a commit
to MikeGoldsmith/opentelemetry-python-genai
that referenced
this pull request
May 15, 2026
Addresses Copilot review feedback: the changelog steps depend on open-telemetry#16 (towncrier setup) which hasn't merged yet. Make the dependency explicit at the top of the doc so it's obvious to any reviewer. Assisted-by: Claude Opus 4.7 (1M context)
MikeGoldsmith
added a commit
to MikeGoldsmith/opentelemetry-python-genai
that referenced
this pull request
May 15, 2026
The note belongs in the PR description as a merge-ordering signal, not in the doc itself where it would have to be removed once open-telemetry#16 lands. Assisted-by: Claude Opus 4.7 (1M context)
eternalcuriouslearner
approved these changes
May 18, 2026
- Drop the Skip Changelog label bullet: most contributors don't have write access, so steering agents toward applying labels is the wrong default. - Drop the trailing link to CONTRIBUTING.md — it's already linked at the top of the file. Assisted-by: Claude Opus 4.7 (1M context)
aabmass
approved these changes
May 18, 2026
This was referenced May 18, 2026
This was referenced May 18, 2026
DylanRussell
added a commit
to DylanRussell/opentelemetry-python-genai
that referenced
this pull request
Jun 25, 2026
…elemetry#20) * docs: add RELEASING.md Documents the per-package independent release model used by this repo, the manual end-to-end release steps with the existing build scripts, and the towncrier-based changelog flow. Calls out missing pieces explicitly: PyPI names are still TBD per package, and contrib's automated release workflows haven't been ported yet. Both tracked in the bootstrap issue. Assisted-by: Claude Opus 4.7 (1M context) * add note about towncrier dependency Addresses Copilot review feedback: the changelog steps depend on open-telemetry#16 (towncrier setup) which hasn't merged yet. Make the dependency explicit at the top of the doc so it's obvious to any reviewer. Assisted-by: Claude Opus 4.7 (1M context) * revert inline towncrier note The note belongs in the PR description as a merge-ordering signal, not in the doc itself where it would have to be removed once open-telemetry#16 lands. Assisted-by: Claude Opus 4.7 (1M context) * port package release workflows from contrib Replaces the manual-release documentation that was originally on this branch with the contrib release workflows for independently released packages. Every publishable package in this repo is independent, so only the per-package workflows apply (no coordinated bulk-release flow). Workflows ported: - [Package] Prepare release: cuts the release branch package-release/<pkg>/v<X>.<Y>.x; opens PRs to bump version and build the changelog via towncrier on both the release branch and main. - [Package] Prepare patch release: opens a patch-bump PR against an existing package release branch. - [Package] Release: publishes the built wheel to PyPI, creates the GitHub release, opens a back-merge PR copying the changelog to main. Supporting scripts ported: - scripts/generate_release_notes.sh - scripts/merge_changelog_to_main.sh - .github/scripts/use-cla-approved-github-bot.sh Adaptations from contrib: - Workflow package dropdowns list the 8 publishable packages in this repo. - backport.yml not ported; no release branches exist yet, will revisit when one does. - PyPI publishing uses a token (secrets.pypi_password), matching contrib. Tracked in open-telemetry#15 to migrate to PyPI trusted publishing once package names are decided and per-package publishers can be set up. RELEASING.md rewritten as a thin doc pointing at the workflows, listing the otelbot / PyPI / branch protection prerequisites, and documenting the pre-existing static "## Unreleased" entries that need manual folding on the first towncrier release per package. Assisted-by: Claude Opus 4.7 (1M context) * drop --discussion-category from gh release create Discussions are not enabled on the opentelemetry-python-genai repo, and there is no `announcements` category, so the flag would cause `gh release create` to fail. Drop it for now; can be re-added in a follow-up if/when Discussions is enabled and an announcements category is created. Picked up from JWinermaSplunk's review on PR open-telemetry#20. Assisted-by: Claude Opus 4.7 (1M context) * restore setup-uv step to package release workflow build_a_package.sh uses `uv run` and `uv build`, so the runner needs uv installed. Removed by mistake earlier. Assisted-by: Claude Opus 4.7 (1M context) * add bulk release workflows with tag-from-main and PyPI trusted publishing Replace contrib's always-on release branches with prep and publish on main, lazy backport branches, release-all orchestration, and OIDC publishing via the pypi GitHub environment. * Simplify release docs and release package list. Rename eachdist.ini exclude_release to release_packages, omit scaffolding packages from release workflows, and focus RELEASING.md on release steps. * style: apply ruff format to scripts/eachdist.py Fix pre-commit ruff-format CI failure on PR open-telemetry#20. --------- Co-authored-by: DylanRussell <[email protected]>
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
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.
Summary
Adopt towncrier for fragment-based changelog management. PRs with user-visible impact add a file under
<package>/.changelog/<PR>.<type>rather than editingCHANGELOG.md, which removes the merge-conflict footgun on backports and concurrent PRs.Every publishable package here releases independently, so each gets its own
[tool.towncrier]config and.changelog/directory — mirroring the independent-package pattern inopentelemetry-python-contrib.What's in this PR:
[tool.towncrier]block in each package'spyproject.toml(7 instrumentations +util-genai)<package>/.changelog/.gitignoreper package<!-- changelog start -->marker above each existing## Unreleasedheadingscripts/changelog_template.j2.github/workflows/changelog.yml: blocks directCHANGELOG.mdedits, requires a fragment, previews rendered changelogs per package; skipped via theSkip Changeloglabeltox -e changelog-previewfor local previewingtowncrierin root dev dependenciesCONTRIBUTING.mdupdated with fragment authoring instructions, and a condensed version added toAGENTS.mdPart of #15.
Notes
Skip Changeloglabel since the change is pure tooling.Skip ChangelogandStalelabels were created on this repo as a prerequisite.prepare-releaseis intentionally not created yet — to be added when release tooling lands (planned name:Prepare Release).tox -e changelog-previewruns cleanly across all 8 packages.