Modern Python Package Release Plan (uv workflow)

[rilma]

Plan: Automated Python Package Releases

Goal

Create a fully automated release workflow where:

• versions come from git tags
• changelogs are generated automatically
• CI builds and publishes the package
• maintainers only create a tag to release

---

Phase 1 -- Version comes from git tags

[project]
name = "pyhwm14"
description = "Python interface for the Horizontal Wind Model 2014 (HWM14)"
readme = "README.md"
requires-python = ">=3.13"
dynamic = ["version"]

This means the version comes from git tags automatically.

---

Phase 2 — Changelog with Towncrier

Towncrier generates release notes automatically.

Create configuration in pyproject.toml.

[tool.towncrier]
package = "mypackage"
directory = "changelog.d"
filename = "CHANGELOG.md"

Create fragments for changes.

Example:

changelog.d/123.feature.md

Contents:

Added support for XYZ.

Types typically used:

feature
bugfix
doc
removal
misc

These fragments are merged into the changelog during release.

---

Phase 3 — Build Package

Build locally with:

uv build

Artifacts appear in:

dist/
  pyhwm14-x.y.z.tar.gz
  pyhwm14-x.y.z.whl

---

Phase 4 — Automated Publishing

Use GitHub Trusted Publishing for PyPI.

Workflow .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -Ls https://astral.sh/uv/install.sh | sh

      - run: uv build

      - run: uv publish

---

Phase 5 — Release Process

Maintainers release by tagging.

git tag v0.3.0
git push --tags

Automated steps:

1. version derived from tag
2. package built
3. package uploaded to PyPI
4. release created

---

Result

Maintainers only need to:

1. merge pull requests
2. create a release tag

Everything else is automated.