👷 ci(release): simplify to one-button workflow (#1727)

* Simplify release flow to one-button workflow

Adopt virtualenv-style release process:
- One "Pre-release" workflow with version bump selector
- Auto-generates version, runs towncrier, commits, tags, and pushes
- Tag push triggers actual release workflow
- Removes complex two-step PR-based flow

Benefits:
- Single button press to release
- Auto version calculation based on changelog fragments
- No manual PR creation/review needed
- Simpler and faster release process

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>

* 📝 docs(release): split zipapp build and upload in diagram

Separating the zipapp build and upload into distinct steps makes the flow
clearer and matches the actual workflow structure where building and uploading
are separate GitHub Actions jobs.

* 📝 docs(release): use sequence diagram and reorganize sections

Replaced the flowchart with a proper mermaid sequence diagram that clearly
shows the interaction between actors (Maintainer, GitHub Actions, scripts,
and external services) during the release process. This makes the temporal
flow and handoffs between systems more obvious.

Moved the diagram under 'What Happens During Release' section where it makes
more logical sense, as it explains the actual execution flow rather than being
a standalone overview.

* 📝 docs(release): remove custom theme for dark mode compatibility

Custom theme colors looked poor on dark backgrounds. Using mermaid's default
theme provides better contrast and readability across both light and dark
modes.

* 📝 docs(release): replace sequence with state diagram

State diagram better represents the release flow as a progression through
distinct states rather than message passing between actors. Shows version
calculation logic, changelog generation, and publication steps as clear
state transitions.

* 📝 docs(release): make state diagram more compact

Condensed the diagram by combining related steps and using shorter labels
while maintaining clarity about the core flow.

* 📝 docs(release): remove diagram, keep prose explanation

The diagram became too simple after compression to provide meaningful value
beyond what the prose already explains clearly.

---------

Signed-off-by: Bernát Gábor <bgabor8@bloomberg.net>

Author: gaborbernat

.github/workflows/bump-changelog.yml

@@ -0,0 +1,44 @@
+name: Pre-release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - auto
+          - major
+          - minor
+          - patch
+        default: auto
+
+env:
+  default-python: "3.13"
+
+jobs:
+  pre-release:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_RELEASE_TOKEN }}
+      - name: Set up Python ${{ env.default-python }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.default-python }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install GitPython packaging towncrier pre-commit
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Generate changelog, commit, tag, and push
+        run: python scripts/release.py --version "${{ inputs.bump }}"

.github/workflows/pre-release.yml

@@ -1,15 +1,10 @@
 name: Release
 
 on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Version to release"
-        required: true
-        type: string
-  pull_request_target:
-    types:
-      - closed
+  push:
+    tags:
+      - "*.*.*"
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -19,50 +14,19 @@ env:
   minimum-supported-python: "3.9"
 
 jobs:
-  create-tag:
-    name: Create the Git tag
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      github.event.pull_request.merged == true
-      && contains(github.event.pull_request.labels.*.name, 'release-version')
-    runs-on: ubuntu-latest
-    outputs:
-      release-tag: ${{ steps.get-version.outputs.version }}
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v6
-      - name: Extract version to be released
-        id: get-version
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-        run: |
-          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
-            echo "version=${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT"
-          else
-            echo "version=${PR_TITLE/: [[:alnum:]]*}" >> "$GITHUB_OUTPUT"
-          fi
-      - name: Bump version and push tag
-        uses: mathieudutour/github-tag-action@v6.2
-        with:
-          custom_tag: "${{ steps.get-version.outputs.version }}"
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          tag_prefix: ""
-
   pypi-publish:
     name: Publish pipx to PyPI
-    needs: create-tag
     runs-on: ubuntu-latest
     environment:
       name: release
       url: https://pypi.org/p/pipx
     permissions:
       id-token: write
     steps:
-      - name: Checkout ${{ needs.create-tag.outputs.release-tag }}
+      - name: Checkout ${{ github.ref_name }}
         uses: actions/checkout@v6
         with:
-          ref: "${{ needs.create-tag.outputs.release-tag }}"
+          ref: "${{ github.ref_name }}"
       - name: Set up Python ${{ env.default-python }}
         uses: actions/setup-python@v6
         with:
@@ -77,7 +41,7 @@ jobs:
 
   create-release:
     name: Create a release on GitHub's UI
-    needs: [pypi-publish, create-tag]
+    needs: pypi-publish
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -87,19 +51,19 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           generate_release_notes: true
-          tag_name: "${{ needs.create-tag.outputs.release-tag }}"
+          tag_name: "${{ github.ref_name }}"
 
   upload-zipapp:
     name: Upload zipapp to GitHub Release
-    needs: [create-release, create-tag]
+    needs: create-release
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
-      - name: Checkout ${{ needs.create-tag.outputs.release-tag }}
+      - name: Checkout ${{ github.ref_name }}
         uses: actions/checkout@v6
         with:
-          ref: "${{ needs.create-tag.outputs.release-tag }}"
+          ref: "${{ github.ref_name }}"
       - name: Set up Python ${{ env.minimum-supported-python }}
         uses: actions/setup-python@v6
         with:
@@ -113,4 +77,4 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           files: pipx.pyz
-          tag_name: "${{ needs.create-tag.outputs.release-tag }}"
+          tag_name: "${{ github.ref_name }}"

.github/workflows/release.yml

@@ -220,15 +220,18 @@ nox -s watch_docs
 
 ## Releasing New `pipx` Versions
 
-To release a new version, manually run the `bump-changelog` action under the *"Actions"* tab, passing it the version to be released. This will create a pull request updating the changelog for the upcoming version, with the `release-version` label. Merging this PR will automatically trigger the release workflows.
+The release process for pipx is designed to be simple and fully automated with a single button press. The workflow automatically determines the next version based on changelog fragments, generates the changelog, creates the release commit, and publishes to PyPI.
 
-Attaching this label to any pull request of which the title follows the format `<Version>: Description` and merging it will trigger the release workflows as well.
+### Initiating a Release
 
-The release workflow consists of publishing:
+Navigate to the **Actions** tab in the GitHub repository and select the **Pre-release** workflow. Click **Run workflow** and choose the appropriate version bump strategy. The `auto` option intelligently determines whether a minor or patch bump is needed by examining the types of changelog fragments present. If new features or removals exist, it performs a minor version bump; otherwise, it increments the patch version. Alternatively, you can explicitly select `major`, `minor`, or `patch` to control the version increment directly.
 
-- the pipx version to PyPI,
-- the documentation to ReadTheDocs,
-- a GitHub release,
-- the `zipapp` to the GitHub release created.
+### What Happens During Release
 
-No need for any other pre or post publish steps.
+Once triggered, the pre-release workflow executes the `scripts/release.py` script which collects all changelog fragments from the `changelog.d/` directory and uses towncrier to generate the updated changelog. It then creates a release commit with the message "Release {version}" and tags it with the version number. After running pre-commit hooks to ensure formatting, both the commit and tag are pushed to the main branch.
+
+The act of pushing a version tag (matching the pattern `*.*.*`) automatically triggers the main release workflow. This workflow builds the project distribution files, publishes the package to PyPI using trusted publishing, creates a GitHub release with auto-generated notes, and builds the zipapp using the minimum supported Python version before uploading it to the GitHub release assets.
+
+### Version Calculation Examples
+
+Starting from version `1.8.0`, the version bump types produce the following results: `auto` with feature fragments becomes `1.9.0`, while `auto` with only bugfixes becomes `1.8.1`. Selecting `major` explicitly jumps to `2.0.0`, `minor` moves to `1.9.0`, and `patch` increments to `1.8.1`. This automation eliminates the need for manual version management and ensures consistency across releases.

docs/contributing.md

@@ -0,0 +1,90 @@
+"""Handles creating a release."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from subprocess import call, check_call
+
+from git import Commit, Remote, Repo, TagReference  # type: ignore[import-not-found]
+from packaging.version import Version
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+CHANGELOG_DIR = ROOT_DIR / "changelog.d"
+
+
+def main(version_str: str, *, push: bool) -> None:
+    repo = Repo(str(ROOT_DIR))
+    if repo.is_dirty():
+        msg = "Current repository is dirty. Please commit any changes and try again."
+        raise RuntimeError(msg)
+    remote = get_remote(repo)
+    remote.fetch()
+    version = resolve_version(version_str, repo)
+    print(f"Releasing {version}")
+    release_commit = release_changelog(repo, version)
+    tag = tag_release_commit(release_commit, repo, version)
+    if push:
+        print("Pushing release commit")
+        repo.git.push(remote.name, "HEAD:main")
+        print("Pushing release tag")
+        repo.git.push(remote.name, tag)
+    print("All done! ✨ 🍰 ✨")
+
+
+def resolve_version(version_str: str, repo: Repo) -> Version:
+    if version_str not in {"auto", "major", "minor", "patch"}:
+        return Version(version_str)
+    latest_tag = repo.git.describe("--tags", "--abbrev=0")
+    parts = [int(x) for x in latest_tag.split(".")]
+    if version_str == "major":
+        parts = [parts[0] + 1, 0, 0]
+    elif version_str == "minor":
+        parts = [parts[0], parts[1] + 1, 0]
+    elif version_str == "patch":
+        parts[2] += 1
+    elif any(CHANGELOG_DIR.glob("*.feature.md")) or any(CHANGELOG_DIR.glob("*.removal.md")):
+        parts = [parts[0], parts[1] + 1, 0]
+    else:
+        parts[2] += 1
+    return Version(".".join(str(p) for p in parts))
+
+
+def get_remote(repo: Repo) -> Remote:
+    upstream_remote = "pypa/pipx"
+    urls = set()
+    for remote in repo.remotes:
+        for url in remote.urls:
+            if url.rstrip(".git").endswith(upstream_remote):
+                return remote
+            urls.add(url)
+    msg = f"Could not find {upstream_remote} remote, has {urls}"
+    raise RuntimeError(msg)
+
+
+def release_changelog(repo: Repo, version: Version) -> Commit:
+    print("Generating release commit")
+    check_call(["towncrier", "build", "--yes", "--version", version.public], cwd=str(ROOT_DIR))
+    call(["pre-commit", "run", "--all-files"], cwd=str(ROOT_DIR))
+    repo.git.add(".")
+    check_call(["pre-commit", "run", "--all-files"], cwd=str(ROOT_DIR))
+    return repo.index.commit(f"Release {version}")
+
+
+def tag_release_commit(release_commit: Commit, repo: Repo, version: Version) -> TagReference:
+    print("Tagging release commit")
+    existing_tags = [x.name for x in repo.tags]
+    if str(version) in existing_tags:
+        print(f"Deleting existing tag {version}")
+        repo.delete_tag(str(version))
+    print(f"Creating tag {version}")
+    return repo.create_tag(str(version), ref=release_commit, force=True)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="release")
+    parser.add_argument("--version", default="auto")
+    parser.add_argument("--no-push", action="store_true")
+    options = parser.parse_args()
+    main(options.version, push=not options.no_push)