What the agent does
The agent reads how the changelog is produced and consumed before it touches it, because in a library it is wired into more than one place. In a package like encode/httpx, CHANGELOG.md follows Keep a Changelog with a ## [UNRELEASED] section at the top holding ### Removed (drop Python 3.8) and ### Added (expose FunctionAuth, #3699) above ## 0.28.1 (6th December, 2024). pyproject.toml builds with hatchling, takes the version from httpx/__version__.py, and uses hatch-fancy-pypi-readme to append a ## Release Information section to the PyPI readme by extracting the first ### block of CHANGELOG.md with the pattern \n(###.+?\n)## . scripts/sync-version greps the second semantic version out of CHANGELOG.md and fails scripts/check if it differs from __version__.py; scripts/check is the first thing scripts/test and the Test Suite workflow run on Python 3.9 through 3.13. .github/CONTRIBUTING.md tells maintainers what must go in the changelog and what must not, and tooling is pinned in requirements.txt.
The agent adds a pinned towncrier line to requirements.txt and a [tool.towncrier] table to pyproject.toml: package = "httpx" so the version comes from __version__.py, directory = "changelog.d", filename = "CHANGELOG.md", start_string = "<!-- towncrier release notes start -->\n", title_format = "## {version} ({project_date})", issue_format = "(#{issue})", and [[tool.towncrier.type]] entries for added, changed, deprecated, removed and fixed whose name values are the Keep a Changelog headings. underlines is set to three empty strings so the Markdown output has no setext underlines. The marker comment goes into CHANGELOG.md directly under the intro paragraph, and the two unreleased entries become changelog.d/3699.added.md and changelog.d/+python38.removed.md, the + prefix being towncrier's spelling for a fragment with no issue number; the ## [UNRELEASED] section is removed.
Then the agent checks each consumer. scripts/sync-version still finds 0.28.1 as the second version in the file, because the first match is the 1.0.0 in the Keep a Changelog link and the marker comment contains no version, so scripts/check passes; the agent runs it to show that. The readme hook's pattern looked for the first ### heading, which was the unreleased section, so the agent runs python -m build and reads the Description of the wheel's METADATA to confirm the Release Information section now carries the latest released entry, and adjusts the pattern if it does not. scripts/check gains towncrier build --draft so a malformed fragment fails the same step that runs ruff and mypy, and [tool.hatch.build.targets.sdist] excludes /changelog.d so fragments never ship.
Finally the release path. The Releasing section of .github/CONTRIBUTING.md is rewritten: contributors add a fragment with their pull request, and the release pull request runs towncrier build --version X.Y.Z --yes, which assembles the section under the marker, deletes the fragments, and leaves CHANGELOG.md ready for the version bump and the existing scripts/publish tag check. The agent runs scripts/check, towncrier build --draft, python -m build and pytest on one Python version in its sandbox and includes the output; the multi-version matrix stays with the workflow.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Set up towncrier changelog fragments for this Python package. Read pyproject.toml, CHANGELOG.md, requirements.txt, scripts/check, scripts/sync-version, scripts/build, scripts/publish, .github/workflows/test-suite.yml and .github/CONTRIBUTING.md first. Pin towncrier in requirements.txt and add a [tool.towncrier] table that reads the version from the package, writes Markdown into CHANGELOG.md under a start marker, and uses the Keep a Changelog headings (Added, Changed, Deprecated, Removed, Fixed) as fragment types. Move every entry in the current unreleased section into fragments under changelog.d, using the + prefix for entries with no issue number, and remove that section. Make sure scripts/sync-version still finds the latest released version, and that the hatch-fancy-pypi-readme fragment that extracts release information from CHANGELOG.md still produces the right text (build the wheel and read its METADATA). Add towncrier build --draft to scripts/check and exclude changelog.d from the sdist. Update the Releasing section of CONTRIBUTING.md. Run scripts/check, towncrier build --draft, python -m build and the tests, include the output, and open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes pyproject.toml (the [tool.towncrier] table and the sdist exclusion), requirements.txt (one pinned line), CHANGELOG.md (the marker added, the unreleased section removed), scripts/check (one more command) and .github/CONTRIBUTING.md (the release steps), and adds changelog.d/3699.added.md, changelog.d/+python38.removed.md and a changelog.d/README.md that names the fragment types. The test and publish workflows, httpx/__version__.py and every source file are untouched.
The description shows the towncrier build --draft output, which is the section the next release would get, the scripts/check result including sync-version, and the Release Information text read back from the built wheel's METADATA. The commands and their output are in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer confirms the fragment type names match the headings they want to keep publishing, reads the draft section once, and decides whether towncrier check against the base branch should also run on pull requests. A follow-up message to the same session can add that workflow step with the full-depth checkout it needs.
Run it on every package whose changelog is edited by hand
A team that maintains several libraries starts one run per repository with POST /o/{org}/sessions, this prompt as input and the repository in resources. Each run reads that package's own build backend, version source and release scripts, so a setuptools project with a HISTORY.rst gets reStructuredText fragments and the matching filename, while a hatch project gets what this page describes.
A request_id that is a UUID v5 of the repository's full name makes a retried call return the run already started. The key's webhook_url delivers run.completed with session_url, so a handler can collect the pull request links and post them where the maintainers read.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Switching a changelog to fragments is mostly archaeology: finding every script, hook and document that reads the file and keeping each one working. The agent does that reading in a sandbox with the package's pinned tooling installed, builds the wheel to see what PyPI would show, and keeps the output rather than a promise.
The pull request carries the draft section towncrier would produce and the passing check script, so a reviewer reads a diff and a draft instead of installing the tool to try it. The same prompt can run across every library a team owns, each in its own sandbox with its own pull request.
Frequently asked questions
Why not just keep editing CHANGELOG.md in each pull request?
Because every contributor edits the same lines at the top of the file, which is the most common merge conflict in a busy library. A fragment is one file per change with a unique name, so pull requests stop conflicting and the release step assembles them in one go.
Will the version check in scripts/sync-version still work?
Yes. It takes the second version-shaped string in CHANGELOG.md, and the first is the 1.0.0 in the Keep a Changelog link. The marker comment adds no version, and removing the unreleased heading, which never had one, changes nothing. The agent runs scripts/check to show it passing.
What about the release notes on PyPI?
The readme hook in pyproject.toml copies the first ### block of CHANGELOG.md into the package description. The agent builds the wheel and reads its METADATA to confirm that block is now the latest released section, and changes the extraction pattern if the move left it pointing at the wrong place.
Does towncrier need to run in CI?
towncrier build --draft runs in scripts/check, so a fragment with an unknown type or a bad name fails the same step as ruff and mypy. towncrier check, which refuses a pull request with no fragment, needs the base branch in the checkout; the pull request says how to add it with fetch-depth: 0 if you want that rule.
More Python jobs
More jobs like this: Hand off a long task
- Wrap Multi-Step Writes in GORM Transactions (GORM)
- Add Transactions to a Prisma App (Prisma)
- Add Transactions to a Sequelize App (Sequelize)