Use a draft release instead of a pre-release for artifact staging (#1081)

Pre-releases do not allow additional artifact uploads when the GitHub
"immutable release" feature is used. It's not clear to me why we use a
pre-release instead of a draft release, which is not user visible and
seems generally superior for staging artifacts.

Author: zanieb

.github/workflows/release.yml

@@ -130,3 +130,4 @@ jobs:
     with:
       tag: ${{ github.event.inputs.tag }}
     secrets: inherit
+

CONTRIBUTING.rst

@@ -37,9 +37,9 @@ Releases
 To cut a release, wait for the "MacOS Python build", "Linux Python build", and
 "Windows Python build" GitHub Actions to complete successfully on the target commit.
 
-Then, run the "Release" GitHub Action to create the release, populate the release artifacts (by
-downloading the artifacts from each workflow, and uploading them to the GitHub Release), and promote
-the SHA via the `latest-release` branch.
+Then, run the "Release" GitHub Action to create a draft release, populate the release artifacts
+(by downloading the artifacts from each workflow, and uploading them to the GitHub Release),
+publish the release, and promote the SHA via the `latest-release` branch.
 
 The "Release" GitHub Action takes, as input, a tag (assumed to be a date in `YYYYMMDD` format) and
 the commit SHA referenced above.
@@ -49,8 +49,8 @@ with the tag `20240419` and the commit SHA `29abc56954fbf5ea812f7fbc3e42d87787d4
 once the "MacOS Python build", "Linux Python build", and "Windows Python build" workflows have
 run to completion on `29abc56`.
 
-When the "Release" workflow is complete, populate the release notes in the GitHub UI and promote
-the pre-release to a full release, again in the GitHub UI.
+When the "Release" workflow is complete, the release will have been published and version metadata
+will have been updated. You can then refine the release notes in the GitHub UI.
 
 At any stage, you can run the "Release" workflow in dry-run mode to avoid uploading artifacts to
 GitHub. Dry-run mode can be executed before or after creating the release itself.

Justfile

@@ -71,28 +71,35 @@ release-set-latest-release tag:
 
   git switch main
 
-# Create a GitHub release object, or reuse an existing prerelease.
+# Create a GitHub release object, or reuse an existing draft release.
 release-create tag:
   #!/usr/bin/env bash
   set -euo pipefail
-  prerelease_exists=$(gh release view {{tag}} --json isPrerelease -t '{{{{.isPrerelease}}' 2>&1 || true)
-  case "$prerelease_exists" in
+  draft_exists=$(gh release view {{tag}} --json isDraft -t '{{{{.isDraft}}' 2>&1 || true)
+  case "$draft_exists" in
     true)
-      echo "note: updating existing prerelease {{tag}}"
+      echo "note: updating existing draft release {{tag}}"
       ;;
     false)
-      echo "error: release {{tag}} already exists"
+      echo "error: release {{tag}} already exists and is not a draft"
       exit 1
       ;;
     "release not found")
-      gh release create {{tag}} --prerelease --notes TBD --verify-tag
+      gh release create {{tag}} --draft --notes TBD --verify-tag
       ;;
     *)
-      echo "error: unexpected gh cli output: $prerelease_exists"
+      echo "error: unexpected gh cli output: $draft_exists"
       exit 1
       ;;
   esac
 
+# Publish the draft GitHub release and promote the tag to latest-release.
+release-finalize tag:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  gh release edit {{tag}} --draft=false --latest
+  just release-set-latest-release {{tag}}
+
 # Upload release artifacts to an S3-compatible mirror bucket with the correct release names.
 # AWS credentials are read from the standard AWS_* environment variables.
 # Requires `release-run` to have been run so that dist/SHA256SUMS exists.
@@ -122,7 +129,7 @@ release-run token commit tag:
   just release-download-distributions {{token}} {{commit}}
   datetime=$(ls dist/cpython-3.10.*-x86_64-unknown-linux-gnu-install_only-*.tar.gz  | awk -F- '{print $8}' | awk -F. '{print $1}')
   just release-upload-distributions {{token}} ${datetime} {{tag}}
-  just release-set-latest-release {{tag}}
+  just release-finalize {{tag}}
 
 # Perform a release in dry-run mode.
 release-dry-run token commit tag: