chore(release): add dry-run to release tool prepare command (#3869)

To enable safe testing of the release pipeline, this change introduces a
--dry-run flag to the prepare command that simulates all repository and
GitHub actions.

This also fixes a few issues with the prepare command not fully working
end-to-end.

Along the way, factor out the code a bit. release.py was over 1000 lines
and
becoming unwieldly.

Author: rickeylev

.github/workflows/prepare_release.yml

@@ -31,6 +31,6 @@ jobs:
       - name: Run Release Preparation Pipeline
         run: |
           # Manual trigger: run full preparation
-          bazel run //tools/private/release -- prepare
+          bazel run //tools/private/release -- prepare --no-dry-run
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

tests/tools/private/release/release_test.py

@@ -12,7 +12,10 @@ py_binary(
     srcs = [
         "gh.py",
         "git.py",
+        "prepare.py",
         "release.py",
+        "release_issue.py",
+        "shell.py",
         "utils.py",
     ],
     main = "release.py",

tools/private/release/BUILD.bazel

@@ -4,12 +4,24 @@
 import os
 import tempfile
 
-from tools.private.release.utils import run_cmd
+from tools.private.release.shell import run_cmd
 
 _REPO = "bazel-contrib/rules_python"
 _LABEL = "type: release"
 
 
+class MultipleTrackingIssuesError(ValueError):
+    """Raised when multiple open tracking issues are found for a version."""
+
+    pass
+
+
+class NoTrackingIssueError(ValueError):
+    """Raised when no open tracking issue is found for a version."""
+
+    pass
+
+
 def list_issues(*, fields, label=None, state=None, search=None):
     """Helper to list issues using gh CLI."""
     cmd = ["gh", "issue", "list", f"--repo={_REPO}"]
@@ -50,13 +62,13 @@ def get_release_tracking_issue(version):
             exact_matches.append(issue)
 
     if not exact_matches:
-        raise ValueError(
+        raise NoTrackingIssueError(
             f"No open tracking issue found matching 'Release {version}' "
             f"in repo {_REPO} with label '{_LABEL}'"
         )
     if len(exact_matches) > 1:
         urls = [issue["url"] for issue in exact_matches]
-        raise ValueError(
+        raise MultipleTrackingIssuesError(
             f"Multiple open tracking issues found for version {version} "
             f"in repo {_REPO} with label '{_LABEL}':\n" + "\n".join(urls)
         )
@@ -138,17 +150,15 @@ def update_issue_body(issue_num, body):
             os.unlink(temp_path)
 
 
-def create_pr(version, branch, issue_num):
+def create_pr(version, issue_num):
     """Creates a pull request for release preparation."""
     return run_cmd(
         "gh",
         "pr",
         "create",
         f"--title=Prepare release v{version}",
         f"--body=Work towards #{issue_num}",
-        f"--head={branch}",
         "--base=main",
-        "--label=release-prepared",
     )
 
 

tools/private/release/gh.py

@@ -2,7 +2,7 @@
 
 import subprocess
 
-from tools.private.release.utils import run_cmd
+from tools.private.release.shell import run_cmd
 
 
 def get_tags():
@@ -24,6 +24,11 @@ def add(*files):
     run_cmd("git", "add", *files, capture_output=False)
 
 
+def add_modified_and_deleted():
+    """Stages all modified and deleted tracked files."""
+    run_cmd("git", "add", "--update", capture_output=False)
+
+
 def commit(message, amend=False, no_edit=False):
     """Commits staged changes, optionally amending the previous commit."""
     cmd = ["git", "commit"]
@@ -36,9 +41,13 @@ def commit(message, amend=False, no_edit=False):
     run_cmd(*cmd, capture_output=False)
 
 
-def push(remote, ref):
+def push(remote, ref, set_upstream=False):
     """Pushes a reference to a remote repository."""
-    run_cmd("git", "push", remote, ref, capture_output=False)
+    cmd = ["git", "push"]
+    if set_upstream:
+        cmd.append("-u")
+    cmd.extend([remote, ref])
+    run_cmd(*cmd, capture_output=False)
 
 
 def fetch(remote="origin", tags=False, force=False):

tools/private/release/git.py

@@ -0,0 +1,144 @@
+import datetime
+import pathlib
+
+from tools.private.release import changelog_news, gh, git
+from tools.private.release.release_issue import update_task_in_body
+from tools.private.release.utils import (
+    determine_next_version,
+    replace_version_next,
+)
+
+
+def cmd_prepare(args):
+    """Executes the prepare subcommand."""
+    print("Fetching upstream to verify fresh release history...")
+    git.fetch(tags=True, force=True)
+
+    # Run pre-check: verify there are no local edits
+    status = git.status()
+    if status:
+        print(
+            "Error: Local edits detected. Workspace must be completely clean"
+            " before running release preparation."
+        )
+        for line in status.splitlines():
+            print(f"  {line}")
+        return 1
+    print("Pre-check passed: Workspace is clean.")
+
+    version = args.version
+    if version is None:
+        version = determine_next_version()
+
+    print(f"Running preparation pipeline for {version}...")
+
+    # 1. Find or create tracking issue (EARLY)
+    # We do this before any write operations (branch creation, commit, push)
+    issue_num = args.issue
+
+    if not issue_num:
+        try:
+            issue_num = gh.get_release_tracking_issue(version)
+            print(f"Tracking issue: #{issue_num}")
+        except gh.MultipleTrackingIssuesError as e:
+            print(f"Error: {e}")
+            return 1
+        except gh.NoTrackingIssueError:
+            # Not found, we need the template
+            template_path = pathlib.Path(
+                ".github/ISSUE_TEMPLATE/release_tracking_template.md"
+            )
+            if not template_path.exists():
+                raise FileNotFoundError(f"Template file not found at {template_path}")
+            template_content = template_path.read_text(encoding="utf-8")
+
+            if args.dry_run:
+                print(
+                    f"[DRY RUN] No active tracking issue found for {version}. Would create a new one."
+                )
+                print(f"[DRY RUN] Title: Release {version}\n{template_content}")
+                issue_num = None  # Keep it None for dry-run prints later
+            else:
+                print(
+                    f"No active tracking issue found for {version}. Creating a new one..."
+                )
+                issue_num = gh.create_tracking_issue(version, template_content)
+                print(f"Tracking issue: #{issue_num}")
+    else:
+        print(f"Tracking issue: #{issue_num}")
+
+    branch_name = f"prepare-{version}"
+
+    # 2. Interleaved git and write operations
+
+    # --- Branch selection/creation ---
+    if git.branch_exists(branch_name):
+        if args.dry_run:
+            print(
+                f"[DRY RUN] Branch {branch_name} already exists. Would checkout existing branch."
+            )
+        else:
+            print(f"Branch {branch_name} already exists. Checking it out...")
+            git.checkout(branch_name)
+    else:
+        if args.dry_run:
+            print(f"[DRY RUN] Would create and checkout branch {branch_name}")
+        else:
+            git.checkout(branch_name, create_branch=True)
+
+    # --- Update files ---
+    if args.dry_run:
+        print(
+            f"[DRY RUN] Would update CHANGELOG.md and version placeholders for {version}"
+        )
+    else:
+        print("Updating changelog and placeholders...")
+        release_date = datetime.date.today().strftime("%Y-%m-%d")
+        changelog_news.update_changelog(version, release_date)
+        replace_version_next(version)
+
+    # --- Commit and Push ---
+    if args.dry_run:
+        print(f"[DRY RUN] Would push branch {branch_name} to origin")
+    else:
+        modified_files = git.status()
+        if not modified_files:
+            print("No files modified by the release tool. Nothing to commit.")
+            return 0
+
+        # Stage all modified and deleted tracked files
+        git.add_modified_and_deleted()
+
+        git.commit(f"Prepare release {version}")
+        git.push("origin", branch_name, set_upstream=True)
+
+    # --- Create PR ---
+    if args.dry_run:
+        target_issue = f"#{issue_num}" if issue_num else "<NEW_ISSUE>"
+        print(
+            f"[DRY RUN] Would create Pull Request for branch {branch_name} targeting issue {target_issue}"
+        )
+    else:
+        pr_url = gh.create_pr(version, issue_num)
+        pr_num = pr_url.split("/")[-1]
+        print(f"Created Pull Request: {pr_url} (PR #{pr_num})")
+
+    # --- Update checklist ---
+    if args.dry_run:
+        target_issue = f"#{issue_num}" if issue_num else "<NEW_ISSUE>"
+        print(
+            f"[DRY RUN] Would update tracking issue {target_issue} checklist 'Prepare Release' task status to PENDING"
+        )
+    else:
+        print(
+            f"Updating tracking issue #{issue_num} checklist 'Prepare Release' task status to PENDING..."
+        )
+        body = gh.get_issue_body(issue_num)
+        metadata = {"status": "pending", "pr": f"#{pr_num}"}
+        updated_body = update_task_in_body(
+            body, "Prepare Release", checked=False, metadata=metadata
+        )
+        gh.update_issue_body(issue_num, updated_body)
+        print("Preparation pipeline completed successfully!")
+
+    return 0