chore: automate release preparation

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ulises-jeremias

.github/workflows/prepare-release.yml

@@ -0,0 +1,70 @@
+name: Prepare release PR
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version, e.g. 0.1.1"
+        required: true
+      notes:
+        description: "Markdown changelog notes for this release"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: prepare-release-${{ github.event.inputs.version }}
+  cancel-in-progress: true
+
+jobs:
+  prepare:
+    name: Prepare release bump
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version-file: .python-version
+
+      - name: Sync workspace
+        run: uv sync --group dev
+
+      - name: Prepare release files
+        env:
+          VERSION: ${{ github.event.inputs.version }}
+          NOTES: ${{ github.event.inputs.notes }}
+        run: |
+          uv run python scripts/prepare_release.py "$VERSION" --notes "$NOTES"
+
+      - name: Verify release notes are extractable
+        env:
+          VERSION: ${{ github.event.inputs.version }}
+        run: |
+          uv run python scripts/extract_release_notes.py "$VERSION" --output /tmp/release-notes.md
+          test -s /tmp/release-notes.md
+
+      - name: Create release PR
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: release/create-awesome-python-app-${{ github.event.inputs.version }}
+          title: "chore(release): prepare ${{ github.event.inputs.version }}"
+          commit-message: "chore(release): prepare ${{ github.event.inputs.version }}"
+          body: |
+            ## Summary
+
+            - bumps `create-python-app-core` and `create-awesome-python-app` to `${{ github.event.inputs.version }}`
+            - updates the CLI dependency on the matching core version
+            - prepends release notes to `CHANGELOG.md`
+
+            ## Release checklist
+
+            - [ ] Review generated version/changelog diff
+            - [ ] Merge this PR
+            - [ ] Tag `create-awesome-python-app@${{ github.event.inputs.version }}`
+            - [ ] Confirm PyPI, Docker, Homebrew, AUR, and distribution smoke workflows
+
+            Closes #195

.github/workflows/publish.yml

@@ -25,6 +25,16 @@ jobs:
         with:
           python-version-file: .python-version
       - run: uv sync --group dev
+      - name: Resolve release version
+        id: release
+        run: |
+          set -euo pipefail
+          VERSION="${GITHUB_REF_NAME#create-awesome-python-app@}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Extract release notes
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          uv run python scripts/extract_release_notes.py "${{ steps.release.outputs.version }}" --output release-notes.md
       - name: Build packages
         run: |
           mkdir -p dist-core dist-cli
@@ -39,14 +49,7 @@ jobs:
         uses: softprops/action-gh-release@v3
         with:
           files: dist/*
-          body: |
-            First public release. Install with:
-
-            ```bash
-            uvx create-awesome-python-app@0.1.0 --help
-            ```
-
-            Catalog: https://github.com/Create-Python-App/cpa-templates
+          body_path: release-notes.md
       - name: Publish create-python-app-core to PyPI
         if: startsWith(github.ref, 'refs/tags/')
         uses: pypa/gh-action-pypi-publish@release/v1

docs/VERSIONING.md

@@ -1,9 +1,43 @@
 # Versioning
 
-CPA uses **GitHub Releases + tags** with hatchling package versions.
+CPA uses **release-prep PRs + GitHub Releases + tags** with hatchling package
+versions.
 
-Recommended flow (release-please or manual tags):
+## Prepare a release PR
 
-1. Bump `version` in package pyproject.toml files
-2. Tag `create-awesome-python-app@X.Y.Z`
-3. `publish.yml` builds and publishes to PyPI via OIDC (see #58)
+Run the `Prepare release PR` workflow manually with:
+
+- `version`: the next CLI/core version, for example `0.1.1`
+- `notes`: markdown release notes to prepend to `CHANGELOG.md`
+
+The workflow runs `scripts/prepare_release.py`, opens a PR, and updates:
+
+- `packages/create-python-app-core/pyproject.toml`
+- `packages/create-awesome-python-app/pyproject.toml`
+- `create-python-app-core` dependency pin in the CLI package
+- both runtime `__version__` files
+- `CHANGELOG.md`
+
+Local equivalent:
+
+```bash
+uv run python scripts/prepare_release.py 0.1.1 --notes "- Fix release automation."
+```
+
+## Publish after merge
+
+After the release-prep PR is merged:
+
+1. Tag `create-awesome-python-app@X.Y.Z`
+2. Push the tag
+3. `publish.yml` builds and publishes both packages to PyPI via OIDC (see #58)
+4. GitHub Release notes are extracted from the matching `CHANGELOG.md` section
+5. Distribution workflows update Docker, Homebrew, and AUR
+
+```bash
+git tag create-awesome-python-app@X.Y.Z
+git push origin create-awesome-python-app@X.Y.Z
+```
+
+Before closing the release issue, confirm PyPI, GitHub Release, Docker,
+Homebrew, AUR, and `smoke-distribution.yml`.

scripts/extract_release_notes.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Extract a single version section from CHANGELOG.md."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def extract_notes(version: str) -> str:
+    lines = (ROOT / "CHANGELOG.md").read_text().splitlines()
+    heading_prefix = f"## {version}"
+    start = next(
+        (idx for idx, line in enumerate(lines) if line.startswith(heading_prefix)),
+        None,
+    )
+    if start is None:
+        raise SystemExit(f"CHANGELOG.md does not contain notes for {version}")
+
+    end = next(
+        (
+            idx
+            for idx, line in enumerate(lines[start + 1 :], start + 1)
+            if line.startswith("## ")
+        ),
+        len(lines),
+    )
+    return "\n".join(lines[start + 1 : end]).strip() + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("version")
+    parser.add_argument("--output", default="release-notes.md")
+    args = parser.parse_args()
+
+    Path(args.output).write_text(extract_notes(args.version))
+    print(f"Wrote release notes for {args.version} to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/prepare_release.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Prepare a release bump across the CPA workspace."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+VERSION_RE = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(?:[a-zA-Z0-9.-]+)?$")
+PROJECT_VERSION_RE = re.compile(r'(?m)^version = "[^"]+"$')
+CORE_DEP_RE = re.compile(r'"create-python-app-core>=[^"]+"')
+PY_VERSION_RE = re.compile(r'__version__ = "[^"]+"')
+
+VERSION_FILES = [
+    ROOT / "packages/create-python-app-core/pyproject.toml",
+    ROOT / "packages/create-awesome-python-app/pyproject.toml",
+    ROOT / "packages/create-python-app-core/src/create_python_app_core/_version.py",
+    ROOT / "packages/create-awesome-python-app/src/create_awesome_python_app/__init__.py",
+]
+
+
+def replace_once(path: Path, pattern: re.Pattern[str], replacement: str) -> None:
+    text = path.read_text()
+    updated, count = pattern.subn(replacement, text, count=1)
+    if count != 1:
+        raise SystemExit(f"Expected one replacement in {path}, got {count}")
+    path.write_text(updated)
+
+
+def update_versions(version: str) -> None:
+    replace_once(
+        ROOT / "packages/create-python-app-core/pyproject.toml",
+        PROJECT_VERSION_RE,
+        f'version = "{version}"',
+    )
+    replace_once(
+        ROOT / "packages/create-awesome-python-app/pyproject.toml",
+        PROJECT_VERSION_RE,
+        f'version = "{version}"',
+    )
+    replace_once(
+        ROOT / "packages/create-awesome-python-app/pyproject.toml",
+        CORE_DEP_RE,
+        f'"create-python-app-core>={version}"',
+    )
+    replace_once(
+        ROOT / "packages/create-python-app-core/src/create_python_app_core/_version.py",
+        PY_VERSION_RE,
+        f'__version__ = "{version}"',
+    )
+    replace_once(
+        ROOT / "packages/create-awesome-python-app/src/create_awesome_python_app/__init__.py",
+        PY_VERSION_RE,
+        f'__version__ = "{version}"',
+    )
+
+
+def update_changelog(version: str, notes: str) -> None:
+    changelog = ROOT / "CHANGELOG.md"
+    text = changelog.read_text()
+    heading = f"## {version}"
+    if heading in text:
+        raise SystemExit(f"CHANGELOG.md already contains {heading}")
+
+    today = datetime.now(UTC).date().isoformat()
+    body = notes.strip() or "- Maintenance release."
+    section = f"## {version} - {today}\n\n{body}\n\n"
+    if not text.startswith("# Changelog\n\n"):
+        raise SystemExit("CHANGELOG.md must start with '# Changelog'")
+    changelog.write_text(text.replace("# Changelog\n\n", f"# Changelog\n\n{section}", 1))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("version", help="Release version, e.g. 0.1.1")
+    parser.add_argument(
+        "--notes",
+        default="- Maintenance release.",
+        help="Markdown notes to insert into CHANGELOG.md",
+    )
+    args = parser.parse_args()
+
+    if not VERSION_RE.match(args.version):
+        raise SystemExit(f"Invalid version: {args.version}")
+
+    for path in VERSION_FILES:
+        if not path.is_file():
+            raise SystemExit(f"Missing expected version file: {path}")
+
+    update_versions(args.version)
+    update_changelog(args.version, args.notes)
+    print(f"Prepared release {args.version}")
+
+
+if __name__ == "__main__":
+    main()