Update changelog/contributors/version bump in one script

3rdparty/python/requirements.txt

@@ -47,3 +47,6 @@ uvicorn[standard]==0.17.6
 
 beautifulsoup4==4.11.1 # Util for webcrawling for pulling in tool versions
 python-gnupg==0.4.9 # For validating signatures
+
+# Only used for release management
+PyGithub==2.0.0rc1

CONTRIBUTORS.md

@@ -1,4 +1,4 @@
-Created by running `./pants run build-support/bin/contributors.py`.
+Created as part of the release process.
 
 + A. Alonso Dominguez
 + Aaron Mitchell

docs/markdown/Contributions/releases/release-process.md

@@ -81,59 +81,34 @@ The process may fail in two ways:
 - The cherry-picking process failed, and tagged the PR with `auto-cherry-picking-failed`: follow the instructions in the comment on the pull request. (This likely means there's merge conflicts that require manual resolution.)
 - the cherry-pick didn't (yet) run: trigger the automation manually by going to [the GitHub Action](https://github.com/pantsbuild/pants/actions/workflows/auto-cherry-picker.yaml), clicking on the "Run workflow" button, and providing the PR number.
 
-### 1. Prepare the changelog
+### 1. Start the release
 
-Update the release page in `src/python/pants/notes` for this release series, e.g. update `src/python/pants/notes/2.9.x.md`.
+From the `main` branch, run `pants run src/python/pants_release/start_release.py -- --new 2.9.0.dev1 --release-manager your_github_username --publish` with the relevant version and your own GitHub username.
 
-Run `git fetch --all --tags` to be sure you have the latest release tags available locally.
+This will create a pull request that:
 
-From the `main` branch, run `./pants run src/python/pants_release/changelog.py -- --prior 2.9.0.dev0 --new 2.9.0.dev1` with the relevant versions.
-
-This will update the release notes file, for you to tweak and commit. The script also prints an `Internal` section to paste into a comment on the prep PR.
-
-You are encouraged to fix typos and tweak change descriptions for clarity to users. Ensure that there is exactly one blank line between descriptions, headers etc.
+1. updates release notes (remember to check over the changes and follow the instructions in the PR to make any updates)
+2. updates contributors
+3. bumps the `VERSION` on `main`, if appropriate
 
 > 🚧 Reminder: always do this against the `main` branch
-> 
+>
 > Even if you are preparing notes for a release candidate, always prepare the notes in a branch based on `main` and, later, target your PR to merge with `main`.
 
-> 📘 See any weird PR titles?
-> 
-> Sometimes, committers accidentally use the wrong title when squashing and merging because GitHub pulls the title from the commit title when there is only one commit. 
-> 
-> If you see a vague or strange title like "fix bug", open the original PR to see if the PR title is more descriptive. If it is, please use the more descriptive title instead.
-
-### 2. Update `CONTRIBUTORS.md`
-
-Run `./pants run build-support/bin/contributors.py`
-
-Take note of any new contributors since the last release so that you can give a shoutout in the announcement email.
-
-If this is a stable release, then you can use `git diff` to find all new contributors since the previous stable release, to give them all a shoutout in the stable release email. E.g.,
-
-```
-git diff release_2.8.0..release_2.9.0 CONTRIBUTORS.md
-```
-
-### 3. `dev` and `a0` - bump the `VERSION`
 
-Change `src/python/pants/VERSION` to the new release, e.g. `2.12.0.dev0`. If you encounter an `a0` version on `main`, then the next release will be for a new release series (i.e. you'll bump from `2.12.0a0` to `2.13.0.dev0`).
+### 2. Merge the pull request
 
-### 4. Post the prep to GitHub
-
-Open a pull request on GitHub to merge into `main`. Post the PR to the `#development` in Slack.  
-
-Merge once approved and green.
+Post the PR to the `#development` in Slack. Merge once approved and green.
 
 > 🚧 Watch out for any recently landed PRs
-> 
-> From the time you put up your release prep until you hit "merge", be careful that no one merges any commits into main. 
-> 
+>
+> From the time you put up your release prep until you hit "merge", be careful that no one merges any commits into main.
+>
 > If they do—and you're doing a `dev` or `a0` release—you should merge `main` into your PR and update the changelog with their changes. It's okay if the changes were internal only, but any public changes must be added to the changelog.
-> 
+>
 > Once you click "merge", it is safe for people to merge changes again.
 
-### 5a. `a0` - create a new Git branch
+### 3a. `a0` - create a new Git branch
 
 For example, if you're releasing `2.9.0a0`, create the branch `2.9.x` by running the below. Make sure you are on your release commit before doing this.
 
@@ -142,7 +117,7 @@ $ git checkout -b 2.9.x
 $ git push upstream 2.9.x
 ```
 
-### 5b. release candidates - cherry-pick and bump the VERSION
+### 3b. release candidates - cherry-pick and bump the VERSION
 
 1. Checkout from `main` into the release branch, e.g. `2.9.x`.
 2. Cherry-pick the release prep using `git cherry-pick <sha>`.

src/python/pants_release/common.py

@@ -5,8 +5,12 @@
 
 import subprocess
 import time
+from pathlib import Path
 from typing import NoReturn
 
+VERSION_PATH = Path("src/python/pants/VERSION")
+CONTRIBUTORS_PATH = Path("CONTRIBUTORS.md")
+
 _SCRIPT_START_TIME = time.time()
 
 _COLOR_BLUE = "\x1b[34m"

src/python/pants_release/generate_release_announcement.py

@@ -2,18 +2,17 @@
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 import argparse
 import json
-from pathlib import Path
 
-from pants_release.common import sorted_contributors
+from pants_release.common import VERSION_PATH, sorted_contributors
 from pants_release.git import git
 
 from pants.util.strutil import softwrap
 
 
 def announcement_text() -> str:
-    version = Path("src/python/pants/VERSION").read_text().strip()
+    version = VERSION_PATH.read_text().strip()
     cur_version_sha, prev_version_sha = git(
-        "log", "-2", "--pretty=format:%h", "src/python/pants/VERSION"
+        "log", "-2", "--pretty=format:%h", str(VERSION_PATH)
     ).splitlines(keepends=False)
     git_range = f"{prev_version_sha}..{cur_version_sha}"
     all_contributors = sorted_contributors(git_range)

src/python/pants_release/git.py

@@ -6,14 +6,25 @@
 import shlex
 import subprocess
 
+import github
+from pants_release.common import die, green
+
+from pants.util.strutil import softwrap
+
 logger = logging.getLogger(__name__)
 
-MAIN_REPO = "https://github.com/pantsbuild/pants"
+MAIN_REPO_SLUG = "pantsbuild/pants"
+MAIN_REPO = f"https://github.com/{MAIN_REPO_SLUG}"
 
 
-def git(*args: None | str, check: bool = True, capture_stdout: bool = True) -> str:
-    """Run `git *args`, skipping any Nones."""
-    cmd = ["git", *(a for a in args if a is not None)]
+def _run(
+    exe: str,
+    args: tuple[None | str, ...],
+    check: bool,
+    capture_stdout: bool,
+    log_stdout: bool = True,
+) -> str:
+    cmd = [exe, *(a for a in args if a is not None)]
     logger.info("running: %s", shlex.join(cmd))
     result = subprocess.run(
         cmd,
@@ -22,10 +33,17 @@ def git(*args: None | str, check: bool = True, capture_stdout: bool = True) -> s
         text=True,
     )
     stdout = "" if result.stdout is None else result.stdout.strip()
-    logger.debug("returncode: %s, stdout: %s", result.returncode, stdout)
+    logger.debug(
+        "returncode: %s, stdout: %s", result.returncode, stdout if log_stdout else "<redacted>"
+    )
     return stdout
 
 
+def git(*args: None | str, check: bool = True, capture_stdout: bool = True) -> str:
+    """Run `git *args`, skipping any Nones."""
+    return _run("git", args, check=check, capture_stdout=capture_stdout)
+
+
 def git_rev_parse(rev: str, *, verify: bool = True, abbrev_ref: bool = False) -> str:
     return git(
         "rev-parse", "--verify" if verify else None, "--abbrev-ref" if abbrev_ref else None, rev
@@ -36,3 +54,30 @@ def git_fetch(rev: str) -> str:
     """Fetch rev (e.g. branch or a SHA) from the upstream repository and return its SHA."""
     git("fetch", MAIN_REPO, rev)
     return git_rev_parse("FETCH_HEAD")
+
+
+def github_repo() -> github.Repository.Repository:
+    # Borrow the token from `gh`, because it works well both interactively (running `gh auth login`
+    # is far more convenient for interactive use than manually generating a token) and in
+    # scripts/automation (it reads the `GH_TOKEN=...` env var, if set)
+    token = _run("gh", ("auth", "token"), check=False, capture_stdout=True, log_stdout=False)
+    if not token:
+        die(
+            softwrap(
+                """
+                Failed to find credentials via `gh auth token`; is https://cli.github.com installed
+                and authenticated? Auth with `gh auth login` or by setting `GH_TOKEN=...` env var.
+                """
+            )
+        )
+
+    try:
+        gh = github.Github(auth=github.Auth.Token(token))
+        user = gh.get_user()
+        repo = gh.get_repo(MAIN_REPO_SLUG)
+    except Exception as e:
+        die(f"Failed to get Github info; is your token valid? {e}")
+    else:
+        green(f"Operating on Github as: @{user.login}")
+
+    return repo

src/python/pants_release/release.py

@@ -26,7 +26,7 @@
 
 import requests
 from packaging.version import Version
-from pants_release.common import banner, die, green
+from pants_release.common import VERSION_PATH, banner, die, green
 from pants_release.git import git, git_rev_parse
 from pants_release.reversion import reversion
 
@@ -387,8 +387,7 @@ def __init__(self) -> None:
             "--date=format:%Y%m%d%H%M",
             self._head_sha,
         )
-        self.pants_version_file = Path("src/python/pants/VERSION")
-        self.pants_stable_version = self.pants_version_file.read_text().strip()
+        self.pants_stable_version = VERSION_PATH.read_text().strip()
 
     @property
     def binary_base_url(self) -> str:
@@ -456,12 +455,12 @@ def get_pgp_program_name() -> str:
 @contextmanager
 def set_pants_version(version: str) -> Iterator[None]:
     """Temporarily rewrite the VERSION file."""
-    original_content = CONSTANTS.pants_version_file.read_text()
-    CONSTANTS.pants_version_file.write_text(version)
+    original_content = VERSION_PATH.read_text()
+    VERSION_PATH.write_text(version)
     try:
         yield
     finally:
-        CONSTANTS.pants_version_file.write_text(original_content)
+        VERSION_PATH.write_text(original_content)
 
 
 def is_cross_platform(wheel_paths: Iterable[Path]) -> bool: