# Add towncrier Changelog Fragments to a Python Package

Yes. An agent configures towncrier for your package, moves the unreleased changelog entries into fragments, keeps your release scripts working, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-towncrier-changelog/python/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add mypy Type Checking to a Python Project's CI](https://getrush.ai/run/add-type-checking/python/)
- [Find Dead Code in a Python Library](https://getrush.ai/run/find-dead-code/python/)
- [Fix "ImportError: cannot import name 'Mapping' from 'collections'"](https://getrush.ai/run/fix-collections-abc-import-error/python/)

## More jobs like this: Hand off a long task

- [Wrap Multi-Step Writes in GORM Transactions](https://getrush.ai/run/add-transactions/gorm/)
- [Add Transactions to a Prisma App](https://getrush.ai/run/add-transactions/prisma/)
- [Add Transactions to a Sequelize App](https://getrush.ai/run/add-transactions/sequelize/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
