Skip to content

ci: introduce towncrier for fragment-based changelog management#16

Merged
aabmass merged 5 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/setup-towncrier
May 18, 2026
Merged

ci: introduce towncrier for fragment-based changelog management#16
aabmass merged 5 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/setup-towncrier

Conversation

@MikeGoldsmith

@MikeGoldsmith MikeGoldsmith commented May 14, 2026

Copy link
Copy Markdown
Member

Summary

Adopt towncrier for fragment-based changelog management. PRs with user-visible impact add a file under <package>/.changelog/<PR>.<type> rather than editing CHANGELOG.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 in opentelemetry-python-contrib.

What's in this PR:

  • [tool.towncrier] block in each package's pyproject.toml (7 instrumentations + util-genai)
  • <package>/.changelog/.gitignore per package
  • Do-not-edit comment and <!-- changelog start --> marker above each existing ## Unreleased heading
  • Shared template at scripts/changelog_template.j2
  • .github/workflows/changelog.yml: blocks direct CHANGELOG.md edits, requires a fragment, previews rendered changelogs per package; skipped via the Skip Changelog label
  • tox -e changelog-preview for local previewing
  • towncrier in root dev dependencies
  • CONTRIBUTING.md updated with fragment authoring instructions, and a condensed version added to AGENTS.md

Part of #15.

Notes

  • This PR carries the Skip Changelog label since the change is pure tooling.
  • The Skip Changelog and Stale labels were created on this repo as a prerequisite. prepare-release is intentionally not created yet — to be added when release tooling lands (planned name: Prepare Release).
  • Verified locally that the per-package draft renders correctly with a throwaway fragment and that tox -e changelog-preview runs cleanly across all 8 packages.

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)
@MikeGoldsmith MikeGoldsmith added the Skip Changelog PR does not require a changelog entry label May 14, 2026
- 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)
Comment thread CONTRIBUTING.md

@lmolkova lmolkova left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
@MikeGoldsmith
MikeGoldsmith marked this pull request as ready for review May 14, 2026 18:34
@MikeGoldsmith
MikeGoldsmith requested a review from a team as a code owner May 14, 2026 18:34
Copilot AI review requested due to automatic review settings May 14, 2026 18:34
@MikeGoldsmith

Copy link
Copy Markdown
Member Author

Ready for review now - I left it in draft while I fixed up the 'Skip Changelog' label, which is working now 👍🏻

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 and opentelemetry-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.

Comment thread .github/workflows/changelog.yml
Comment thread .github/workflows/changelog.yml
Comment thread util/opentelemetry-util-genai/CHANGELOG.md
- 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)
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
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)
- 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)
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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Skip Changelog PR does not require a changelog entry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants