Add create-empty-github-release entrypoint; fix latest-release flag

The new create-empty-github-release entrypoint lets a release workflow
create the GitHub release at the version tag early, so release artefacts
can be attached to it as they are built across per-platform jobs. The
release is created with an empty body and is explicitly not marked as
the latest release; a later publish-release-notes-to-github call fills
in the body. If a release for the tag already exists, the entrypoint is
a no-op so that restart paths do not clobber partial progress.

publish-release-notes-to-github now sets make_latest=true when creating
or updating the release. Without this, GitHub's "releases/latest" URL
did not correspond to the most recent release for repos using this
action — an oversight that becomes load-bearing as consumers (starting
with ponyup) begin pulling binaries from GitHub Releases. The script
also gains GithubException handling around update_release and
create_git_release so API failures exit with a clear message instead
of a traceback.

PyGithub is bumped to 2.9.0 because make_latest was added in 2.1.0.
The bump also deprecates the positional Github(token) constructor, so
both existing PyGithub-using scripts are updated to the Auth.Token form
to avoid DeprecationWarning noise in release logs. Because PyGithub's
create_git_release defaults make_latest to "true" (not NotSet), the
new entrypoint must pass make_latest="false" explicitly to keep the
empty release from being marked latest.

Design: ponylang/ponyup#406

Author: SeanTAllen

Dockerfile

@@ -11,7 +11,7 @@ RUN apt-get update \
 
 RUN pip3 install --break-system-packages\
   gitpython \
-  pygithub==1.55 \
+  pygithub==2.9.0 \
   pylint \
   pyyaml \
   zulip

README.md

@@ -152,12 +152,16 @@ jobs:
 
 ### Release
 
-The meat of the release process. This is the workflow that builds our actual release artefacts, updates documentation and whatever else. Release-bot only provides two commands to be used in this workflow.
+The meat of the release process. This is the workflow that builds our actual release artefacts, updates documentation and whatever else. Release-bot provides three commands to be used in this workflow.
 
 - pre-artefact-changelog-check
 
 Can be used to verify that the release workflow wasn't "accidentally" triggered.
 
+- create-empty-github-release
+
+Creates an empty GitHub release for the version tag so that release artefacts can be attached to it as they are built. Not required unless you need a GitHub release for artefact attachment.
+
 - trigger-release-announcement
 
 Is used to start the `announce-a-release` workflow and is meant to be run after all artefact building has completed.
@@ -356,6 +360,30 @@ An example step config:
           GIT_USER_EMAIL: "ponylang.main@gmail.com"
 ```
 
+### create-empty-github-release
+
+Creates an empty GitHub release for the tag being released. The release is created with an empty body, not marked as a draft, and not marked as the latest release. The release body and the "latest" flag can be set later by `publish-release-notes-to-github`.
+
+This command exists so that release artefacts can be attached to the GitHub release as they are built during the `release` workflow. It should be run as part of the `pre-artefact-creation` job, after `pre-artefact-changelog-check`.
+
+If a release for the tag already exists, `create-empty-github-release` does nothing. This means the command is safe to re-run if the `release` workflow has to be restarted.
+
+- **Must** be triggered by an `X.Y.Z` tag push.
+- **Should** be run after `pre-artefact-changelog-check` and before any artefact building steps.
+
+`create-empty-github-release` requires a GitHub personal access token with `public_repo` access. The personal access token needs to be passed in the environment variable `RELEASE_TOKEN`.
+
+An example step config:
+
+```yml
+      - name: Create empty GitHub release
+        uses: docker://ghcr.io/ponylang/release-bot-action:0.6.5
+        with:
+          entrypoint: create-empty-github-release
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+```
+
 ### delete-announcement-tag
 
 Deletes the `announce-X.Y.Z` tag that is used to kick off various release announcement commands.

scripts/add-announcement-to-last-week-in-pony

@@ -5,6 +5,7 @@
 import os
 import re
 import sys
+from github import Auth
 from github import Github
 
 ENDC = '\033[0m'
@@ -25,14 +26,14 @@ if 'GITHUB_REPOSITORY' not in os.environ:
     print(ERROR + "GITHUB_REPOSITORY needs to be set in env. Exiting." + ENDC)
     sys.exit(1)
 
-# version is in the form of "refs/tags/release-1.0.0" where the version is 1.0.0
+# version is in the form of "refs/tags/announce-1.0.0" where the version is 1.0.0
 version = re.sub('refs/tags/announce-', '', os.environ['GITHUB_REF'])
 
 release_repo = os.environ['GITHUB_REPOSITORY']
 
 print(INFO + "Adding release to Last Week in Pony..." + ENDC)
 
-g = Github(os.environ['RELEASE_TOKEN'])
+g = Github(auth=Auth.Token(os.environ['RELEASE_TOKEN']))
 repo = g.get_repo('ponylang/ponylang-website')
 results = repo.get_issues(labels=['last-week-in-pony'])
 if results.totalCount == 0:

scripts/create-empty-github-release

@@ -0,0 +1,66 @@
+#!/usr/bin/python3
+# pylint: disable=C0103
+# pylint: disable=C0114
+
+import os
+import re
+import sys
+from github import Auth
+from github import Github
+from github import GithubException
+from github import UnknownObjectException
+
+ENDC = '\033[0m'
+ERROR = '\033[31m'
+INFO = '\033[34m'
+NOTICE = '\033[33m'
+
+# validate env
+if 'RELEASE_TOKEN' not in os.environ:
+    print(ERROR + "RELEASE_TOKEN needs to be set in env. Exiting." + ENDC)
+    sys.exit(1)
+
+if 'GITHUB_REF' not in os.environ:
+    print(ERROR + "GITHUB_REF needs to be set in env. Exiting." + ENDC)
+    sys.exit(1)
+
+if 'GITHUB_REPOSITORY' not in os.environ:
+    print(ERROR + "GITHUB_REPOSITORY needs to be set in env. Exiting." + ENDC)
+    sys.exit(1)
+
+# version is in the form of "refs/tags/1.0.0" where the version is 1.0.0
+version = re.sub('refs/tags/', '', os.environ['GITHUB_REF'])
+
+g = Github(auth=Auth.Token(os.environ['RELEASE_TOKEN']))
+repo = g.get_repo(os.environ['GITHUB_REPOSITORY'])
+
+# If the release already exists, leave it alone. A prior run may have
+# uploaded assets, populated the body, or set the "latest" flag; modifying
+# any of that here would clobber recovery paths. Only create the release
+# when it's missing.
+print(INFO + "Checking for existing GitHub release for " + version + "..."
+      + ENDC)
+try:
+    repo.get_release(version)
+    print(INFO + "Release already exists. Not modifying." + ENDC)
+    sys.exit(0)
+except UnknownObjectException:
+    print(INFO + "Release does not exist. Creating empty release." + ENDC)
+except GithubException as e:
+    print(ERROR + f"GitHub API error: {e.status} {e.data}" + ENDC,
+          file=sys.stderr)
+    sys.exit(1)
+
+# Explicitly set make_latest="false" so the empty-body release is not
+# marked as the "latest" release. The "latest" flag is deferred until
+# publish-release-notes-to-github runs. PyGithub's create_git_release
+# defaults make_latest to "true", so the argument must be supplied.
+try:
+    repo.create_git_release(tag=version, name=version, message="",
+                            draft=False, prerelease=False,
+                            make_latest="false")
+    print(INFO + "Empty release created." + ENDC)
+except GithubException as e:
+    print(ERROR + f"GitHub API error: {e.status} {e.data}" + ENDC,
+          file=sys.stderr)
+    sys.exit(1)

scripts/publish-release-notes-to-github

@@ -7,7 +7,9 @@ from pathlib import Path
 import re
 import subprocess
 import sys
+from github import Auth
 from github import Github
+from github import GithubException
 from github import UnknownObjectException
 
 ENDC = '\033[0m'
@@ -28,7 +30,7 @@ if 'GITHUB_REPOSITORY' not in os.environ:
     print(ERROR + "GITHUB_REPOSITORY needs to be set in env. Exiting." + ENDC)
     sys.exit(1)
 
-# version is in the form of "refs/tags/release-1.0.0" where the version is 1.0.0
+# version is in the form of "refs/tags/announce-1.0.0" where the version is 1.0.0
 version = re.sub('refs/tags/announce-', '', os.environ['GITHUB_REF'])
 
 release_repo = os.environ['GITHUB_REPOSITORY']
@@ -62,16 +64,30 @@ else:
     print(INFO + "No CHANGELOG.md found." + ENDC)
 
 
-g = Github(os.environ['RELEASE_TOKEN'])
+g = Github(auth=Auth.Token(os.environ['RELEASE_TOKEN']))
 repo = g.get_repo(os.environ['GITHUB_REPOSITORY'])
 
 print(INFO + "Uploading release notes..." + ENDC)
 # check to see if the release already exists
+ghrelease = None
 try:
     ghrelease = repo.get_release(version)
-    print(INFO + "Release already exists. Updating release notes." + ENDC)
-    ghrelease.update_release(name=version, message=release_notes)
 except UnknownObjectException:
-    print(INFO + "Release does not exist. Creating release." + ENDC)
-    repo.create_git_release(version, version, release_notes)
+    pass
+except GithubException as e:
+    print(ERROR + f"GitHub API error: {e.status} {e.data}" + ENDC)
+    sys.exit(1)
+
+try:
+    if ghrelease is not None:
+        print(INFO + "Release already exists. Updating release notes." + ENDC)
+        ghrelease.update_release(name=version, message=release_notes,
+                                 make_latest="true")
+    else:
+        print(INFO + "Release does not exist. Creating release." + ENDC)
+        repo.create_git_release(version, version, release_notes,
+                                make_latest="true")
+except GithubException as e:
+    print(ERROR + f"GitHub API error: {e.status} {e.data}" + ENDC)
+    sys.exit(1)
 print(INFO + "Release notes uploaded." + ENDC)