Package Releases

Version Bumping¶

ap bump increments your project version using uv’s uv version --bump under the hood, then commits the change (bump: version A → B) and tags it (e.g. v0.1.0). Bumps to a stable version also add the new release’s section to CHANGELOG.md in the same commit, see Changelog.

Commands¶

• ap bump — bump version within the current release phase

  • dev versions: 0.1.0.dev3 → 0.1.0.dev4

  • pre-releases: 0.1.0a1 → 0.1.0a2

  • stable versions: 0.3.19 → 0.3.20 (patch)

• ap bump --minor / ap bump --major — bump the minor / major version instead of patch (stable versions only, e.g., 0.3.19 → 0.4.0 / 1.0.0)

• ap bump --pre — bump to a pre-release version (e.g., 0.1.0.dev3 → 0.1.0rc0)

• ap bump --release — bump to a release version (e.g., 0.1.0rc0 → 0.1.0), only allowed on the default branch (e.g. main)

  • NOTE: This command will automatically trigger the release workflow, you don’t need to run ap release manually.

PyPI and GitHub Releases¶

If you agreed to create the release workflow during ap init, afterpython creates a GitHub Actions workflow (.github/workflows/release.yml) that publishes your package to PyPI and creates GitHub releases. The GitHub releases’ notes are generated by git-cliff, see Release Notes.

PyPI Setup¶

To enable trusted publishing on PyPI:

1. Go to PyPI and navigate to your project

2. Click Manage → Publishing (left sidebar)

3. Under the GitHub tab, fill in:

   • Owner: Your GitHub username or organization name

   • Repository: Your repository name

   • Workflow name: release.yml

Releasing Your Package¶

ap release manually pushes the git tag created by ap bump to GitHub, which triggers the release.yml workflow. This command is unnecessary if you’ve already successfully run ap bump --release.

Commands:

• ap release — release the current version to PyPI and GitHub

• ap release --force — force release even for development versions

Semantic Release 🚧¶

Changelog¶

afterpython generates CHANGELOG.md from your commit messages with git-cliff, configured in afterpython/cliff.toml. Commits are grouped by their commit type (e.g. Features, Bug Fixes), and commits that don’t follow the Conventional Commits format are left out. If your branch tracks a GitHub remote, each version links to its compare page on GitHub (e.g. v0.3.19...v0.4.0) and (#123) in a commit message links to the pull request.

ap init creates afterpython/cliff.toml from git-cliff’s default configuration if you agree to it, or run ap init cliff later. Edit it to change what the changelog looks like, see git-cliff’s configuration docs.

Keep all your git-cliff settings in afterpython/cliff.toml, not in pyproject.toml ([tool.git-cliff]) or a cliff.toml at the project root. If ap init finds an existing git-cliff config there, it skips the git-cliff setup; remove it and run ap init cliff to set it up again.

Commands¶

• ap changelog — preview the unreleased changes, i.e. the section the next stable ap bump will add to CHANGELOG.md

• ap changelog <args> — run git-cliff with afterpython/cliff.toml and your arguments instead, e.g.

  • ap changelog --latest — show the latest release

  • ap changelog -o CHANGELOG.md — regenerate the whole changelog from git history (overwrites manual edits)

Updating the Changelog¶

Every ap bump to a stable version (e.g. 0.3.19 → 0.3.20, 0.4.0rc1 → 0.4.0) adds the new release’s section to the top of CHANGELOG.md and commits it together with the version change, so the tagged commit already contains its own release notes.

• The first time, CHANGELOG.md is created from your whole git history.

• After that, only the new section is added, so you can freely edit CHANGELOG.md (e.g. remove or reword small commits) and commit your edits; they are kept.

• Before committing, ap bump opens CHANGELOG.md in git’s editor (the one git commit uses) so you can edit the new section. Save and close it to commit the bump; to abort, press Ctrl+C or exit the editor with an error (e.g. :cq in vim), which undoes the whole bump. Use ap bump --no-edit to skip the editor.

  • GUI editors need to wait for the file to be closed, e.g. git config --global core.editor "zed --wait".

• Dev and pre-release bumps (e.g. 0.4.0rc0) don’t change CHANGELOG.md. Their commits are included in the next stable release’s section, so 0.4.0’s section lists everything since 0.3.19.

• Commit or stash your own edits to CHANGELOG.md before running ap bump.

Release Notes¶

The release workflow uses git-cliff to write the notes of each GitHub release:

• stable releases (e.g. v0.4.0): everything since the previous stable release, the same as their CHANGELOG.md section

• dev and pre-releases (e.g. v0.4.0rc1): what’s new since the previous release (e.g. v0.4.0rc0)

Release notes are generated from git history, not from CHANGELOG.md, so manual edits to CHANGELOG.md don’t show up in them.