Merge pull request #65 from robust-python/feature/improve-demo-branching-pattern

Feature/improve demo branching pattern

Author: 56kyle

.env

@@ -2,10 +2,22 @@
 # Users can override these by creating a .env.local file (not committed to git)
 
 # App author name used for cache directory paths
-COOKIECUTTER_ROBUST_PYTHON_APP_AUTHOR=robust-python
+COOKIECUTTER_ROBUST_PYTHON__DEMOS_CACHE_FOLDER=""
 
-# Main branch name (typically used for stable releases)
-COOKIECUTTER_ROBUST_PYTHON_MAIN_BRANCH=main
+COOKIECUTTER_ROBUST_PYTHON__APP_NAME="cookiecutter-robust-python"
+COOKIECUTTER_ROBUST_PYTHON__APP_AUTHOR="robust-python"
+COOKIECUTTER_ROBUST_PYTHON__REMOTE="origin"
+COOKIECUTTER_ROBUST_PYTHON__MAIN_BRANCH="main"
+COOKIECUTTER_ROBUST_PYTHON__DEVELOP_BRANCH="develop"
 
-# Development branch name (where feature development occurs)
-COOKIECUTTER_ROBUST_PYTHON_DEVELOP_BRANCH=develop
+ROBUST_PYTHON_DEMO__APP_NAME="robust-python-demo"
+ROBUST_PYTHON_DEMO__APP_AUTHOR="robust-python"
+ROBUST_PYTHON_DEMO__REMOTE="origin"
+ROBUST_PYTHON_DEMO__MAIN_BRANCH="main"
+ROBUST_PYTHON_DEMO__DEVELOP_BRANCH="develop"
+
+ROBUST_MATURIN_DEMO__APP_NAME="robust-maturin-demo"
+ROBUST_MATURIN_DEMO__APP_AUTHOR="robust-python"
+ROBUST_MATURIN_DEMO__REMOTE="origin"
+ROBUST_MATURIN_DEMO__MAIN_BRANCH="main"
+ROBUST_MATURIN_DEMO__DEVELOP_BRANCH="develop"

.github/workflows/sync-demos.yml

@@ -0,0 +1,48 @@
+name: sync-demo.yml
+on:
+  pull_request:
+    branches:
+      - develop
+
+env:
+  COOKIECUTTER_ROBUST_PYTHON_PROJECT_DEMOS_FOLDER: ${{ github.workspace }}
+  COOKIECUTTER_ROBUST_PYTHON__DEMOS_CACHE_FOLDER: ${{ github.workspace }}
+  COOKIECUTTER_ROBUST_PYTHON__APP_AUTHOR: ${{ github.repository_owner }}
+  ROBUST_PYTHON_DEMO__APP_AUTHOR: ${{ github.repository_owner }}
+  ROBUST_MATURIN_DEMO__APP_AUTHOR: ${{ github.repository_owner }}
+
+jobs:
+  update-demo:
+    name: Update Demo
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        demo_name:
+          - "robust-python-demo"
+          - "robust-maturin-demo"
+    steps:
+      - name: Checkout Template
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.repository }}
+          path: cookiecutter-robust-python
+
+      - name: Checkout Demo
+        uses: actions/checkout@v4
+        with:
+          repository: "${{ github.repository_owner }}/${{ matrix.demo_name }}"
+          path: ${{ matrix.demo_name }}
+          ref: develop
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Update Demo
+        working-directory: "${{ github.workspace }}/cookiecutter-robust-python"
+        run: "uvx nox -s 'update-demo(${{ matrix.demo_name }})' -- --branch-override ${{ github.head_ref }}"

docs/_static/cookiecutter-robust-python-banner.png

@@ -6,7 +6,10 @@
 
 import os
 import shutil
+from dataclasses import asdict
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 import nox
 import platformdirs
@@ -66,6 +69,41 @@
 )
 
 
+@dataclass
+class RepoMetadata:
+    """Metadata for a given repo."""
+    app_name: str
+    app_author: str
+    remote: str
+    main_branch: str
+    develop_branch: str
+
+
+TEMPLATE: RepoMetadata = RepoMetadata(
+    app_name=os.getenv("COOKIECUTTER_ROBUST_PYTHON__APP_NAME"),
+    app_author=os.getenv("COOKIECUTTER_ROBUST_PYTHON__APP_AUTHOR"),
+    remote=os.getenv("COOKIECUTTER_ROBUST_PYTHON__REMOTE"),
+    main_branch=os.getenv("COOKIECUTTER_ROBUST_PYTHON__MAIN_BRANCH"),
+    develop_branch=os.getenv("COOKIECUTTER_ROBUST_PYTHON__DEVELOP_BRANCH")
+)
+
+PYTHON_DEMO: RepoMetadata = RepoMetadata(
+    app_name=os.getenv("ROBUST_PYTHON_DEMO__APP_NAME"),
+    app_author=os.getenv("ROBUST_PYTHON_DEMO__APP_AUTHOR"),
+    remote=os.getenv("ROBUST_PYTHON_DEMO__REMOTE"),
+    main_branch=os.getenv("ROBUST_PYTHON_DEMO__MAIN_BRANCH"),
+    develop_branch=os.getenv("ROBUST_PYTHON_DEMO__DEVELOP_BRANCH")
+)
+
+MATURIN_DEMO: RepoMetadata = RepoMetadata(
+    app_name=os.getenv("ROBUST_MATURIN_DEMO__APP_NAME"),
+    app_author=os.getenv("ROBUST_MATURIN_DEMO__APP_AUTHOR"),
+    remote=os.getenv("ROBUST_MATURIN_DEMO__REMOTE"),
+    main_branch=os.getenv("ROBUST_MATURIN_DEMO__MAIN_BRANCH"),
+    develop_branch=os.getenv("ROBUST_MATURIN_DEMO__DEVELOP_BRANCH")
+)
+
+
 @nox.session(python=DEFAULT_TEMPLATE_PYTHON_VERSION, name="generate-demo")
 def generate_demo(session: Session) -> None:
     """Generates a project demo using the cookiecutter-robust-python template."""
@@ -143,17 +181,26 @@ def test(session: Session) -> None:
     session.run("pytest", "tests")
 
 
-@nox.parametrize(arg_names="add_rust_extension", arg_values_list=[False, True], ids=["no-rust", "rust"])
+@nox.parametrize(
+    arg_names="demo",
+    arg_values_list=[PYTHON_DEMO, MATURIN_DEMO],
+    ids=["robust-python-demo", "robust-maturin-demo"]
+)
 @nox.session(python=DEFAULT_TEMPLATE_PYTHON_VERSION, name="update-demo")
-def update_demo(session: Session, add_rust_extension: bool) -> None:
+def update_demo(session: Session, demo: RepoMetadata) -> None:
     session.log("Installing script dependencies for updating generated project demos...")
     session.install("cookiecutter", "cruft", "platformdirs", "loguru", "python-dotenv", "typer")
 
     session.log("Updating generated project demos...")
     args: list[str] = [*UPDATE_DEMO_OPTIONS]
-    if add_rust_extension:
+    if "maturin" in demo.app_name:
         args.append("--add-rust-extension")
-    session.run("python", UPDATE_DEMO_SCRIPT, *args)
+
+    if session.posargs:
+        args.extend(session.posargs)
+
+    demo_env: dict[str, Any] = {f"ROBUST_DEMO__{key.upper()}": value for key, value in asdict(demo).items()}
+    session.run("python", UPDATE_DEMO_SCRIPT, *args, env=demo_env)
 
 
 @nox.session(python=False, name="release-template")

noxfile.py

@@ -1,4 +1,14 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "cookiecutter",
+#   "cruft",
+#   "python-dotenv",
+#   "typer",
+# ]
+# ///
 """Python script for generating a demo project."""
+
 import sys
 from pathlib import Path
 from typing import Annotated

scripts/generate-demo.py

@@ -1,3 +1,14 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#   "cookiecutter",
+#   "cruft",
+#   "python-dotenv",
+#   "retrocookie",
+#   "typer",
+# ]
+# ///
+
 import os
 from pathlib import Path
 from typing import Annotated
@@ -6,10 +17,11 @@
 import typer
 from retrocookie.core import retrocookie
 
+from util import DEMO
 from util import git
 from util import FolderOption
 from util import in_new_demo
-from util import require_clean_and_up_to_date_repo
+from util import require_clean_and_up_to_date_demo_repo
 
 
 # These still may need linted, but retrocookie shouldn't be used on them
@@ -29,23 +41,22 @@ def lint_from_demo(
     no_cache: Annotated[bool, typer.Option("--no-cache", "-n")] = False
 ) -> None:
     """Runs precommit in a generated project and matches the template to the results."""
-    develop_branch: str = os.getenv("COOKIECUTTER_ROBUST_PYTHON_DEVELOP_BRANCH", "develop")
     with in_new_demo(
         demos_cache_folder=demos_cache_folder,
         add_rust_extension=add_rust_extension,
         no_cache=no_cache
     ) as demo_path:
-        require_clean_and_up_to_date_repo()
-        git("checkout", develop_branch)
+        require_clean_and_up_to_date_demo_repo(demo_path=demo_path)
+        git("checkout", DEMO.develop_branch)
         git("branch", "-D", "temp/lint-from-demo", ignore_error=True)
-        git("checkout", "-b", "temp/lint-from-demo", develop_branch)
+        git("checkout", "-b", "temp/lint-from-demo", DEMO.develop_branch)
         pre_commit.main.main(["run", "--all-files", "--show-diff-on-failure"])
 
         for path in IGNORED_FILES:
             git("checkout", "HEAD", "--", path)
         git("add", ".")
         git("commit", "-m", "meta: lint-from-demo", "--no-verify")
-    retrocookie(instance_path=demo_path, commits=[f"{develop_branch}..temp/lint-from-demo"])
+    retrocookie(instance_path=demo_path, commits=[f"{DEMO.develop_branch}..temp/lint-from-demo"])
 
 
 if __name__ == '__main__':

scripts/lint-from-demo.py

@@ -0,0 +1,96 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#    "cookiecutter",
+#    "cruft",
+#    "python-dotenv",
+#    "typer",
+# ]
+# ///
+import itertools
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from cookiecutter.utils import work_in
+from loguru import logger
+
+from util import get_current_branch
+from util import get_demo_name
+from util import gh
+from util import git
+from util import nox
+from util import require_clean_and_up_to_date_demo_repo
+from util import FolderOption
+from util import DEMO
+
+
+cli: typer.Typer = typer.Typer()
+
+
+@cli.callback(invoke_without_command=True)
+def release_demo(
+    demos_cache_folder: Annotated[Path, FolderOption("--demos-cache-folder", "-c")],
+    add_rust_extension: Annotated[bool, typer.Option("--add-rust-extension", "-r")] = False
+) -> None:
+    """Creates a release of the demo's current develop branch if changes exist."""
+    demo_name: str = get_demo_name(add_rust_extension=add_rust_extension)
+    demo_path: Path = demos_cache_folder / demo_name
+
+    with work_in(demo_path):
+        require_clean_and_up_to_date_demo_repo(demo_path)
+        git("checkout", DEMO.develop_branch)
+        try:
+            nox("setup-release", "--", "MINOR")
+            logger.success(f"Successfully created release {demo_name}")
+            gh("repo", "set-default", DEMO.app_author, DEMO.app_name)
+
+        except subprocess.CalledProcessError as error:
+            logger.warning(f"Failed to setup release: {error}")
+            _rollback_failed_release()
+            raise error
+
+        git("push", "-u")
+        _create_demo_pr()
+
+
+def _rollback_failed_release() -> None:
+    """Returns the demo repo back to the state it was prior to the release attempt."""
+    starting_demo_branch: str = get_current_branch()
+
+    if starting_demo_branch != "develop":
+        git("checkout", DEMO.develop_branch)
+
+    git("checkout", ".")
+    git("branch", "-D", starting_demo_branch)
+
+
+def _create_demo_pr() -> None:
+    """Creates a pull request to merge the demo's feature branch into ."""
+    current_branch: str = get_current_branch()
+    if not current_branch.startswith("release/"):
+        raise ValueError("Not in a release branch, canceling PR creation.")
+    title: str = current_branch.capitalize()
+    release_notes: str = __get_demo_release_notes()
+
+    pr_kwargs: dict[str, str] = {
+        "--title": title,
+        "--body": release_notes,
+        "--assignee": "@me",
+        "--base": "main",
+    }
+    command: list[str] = ["gh", "pr", "create", *itertools.chain(pr_kwargs.items())]
+    subprocess.run(command, check=True)
+
+
+def __get_demo_release_notes() -> str:
+    """Returns the release notes for the demo."""
+    temp_folder: Path = Path(tempfile.mkdtemp()).resolve()
+    notes_path: Path = temp_folder / "body.md"
+    command: list[str] = ["uv", "run", "./scripts/get-release-notes.py", notes_path]
+    subprocess.run(command, check=True)
+
+    notes_contents: str = notes_path.read_text()
+    return notes_contents