Split "announce-a-release" into multiple different commands

Previously, release-bot-action had a command `announce-a-release` that did multiple things. It:

- Published release notes to GitHub
- Announced the release in the #announce stream of the Pony Zulip
- Added a note about the release to LWIP
- Deleted the `announce-X.Y.Z` tag used to trigger the command
- Rotated the release notes

In keeping with our project to break release-bot-action into a series of fine-grained commands, announce-a-release has been broken apart into multiple commands that can be called from steps in a GitHub actions workflow to compose functionality together on a per-project basis.

Those new commands covered in detail in our updated `announce-a-release` example in README.md. The new step commands are:

- add-announcement-to-last-week-in-pony.bash
- delete-announcement-tag.bash
- publish-release-notes-to-github.bash
- rotate-release-notes.bash
- send-announcement-to-pony-zulip.bash

.release-notes/split-announce.md

@@ -0,0 +1,19 @@
+## Split "announce-a-release" into multiple different commands
+
+Previously, release-bot-action had a command `announce-a-release` that did multiple things. It:
+
+- Published release notes to GitHub
+- Announced the release in the #announce stream of the Pony Zulip
+- Added a note about the release to LWIP
+- Deleted the `announce-X.Y.Z` tag used to trigger the command
+- Rotated the release notes
+
+In keeping with our project to break release-bot-action into a series of fine-grained commands, announce-a-release has been broken apart into multiple commands that can be called from steps in a GitHub actions workflow to compose functionality together on a per-project basis.
+
+Those new commands covered in detail in our updated `announce-a-release` example in README.md. The new step commands are:
+
+- add-announcement-to-last-week-in-pony.bash
+- delete-announcement-tag.bash
+- publish-release-notes-to-github.bash
+- rotate-release-notes.bash
+- send-announcement-to-pony-zulip.bash

README.md

@@ -189,11 +189,23 @@ trigger-release-announcement, by default, will extract the version being release
 
 ## announce-a-release
 
-Announces a release after artefacts have been built:
+Announces the release in a variety of channels.
 
-- Publishes release notes to GitHub
-- Announces in the #announce stream of Zulip
-- Adds a note about the release to LWIP
+There are currently three possible channels that you can announce your release: GitHub release notes, the Ponylang Zulip, and the Pony newsletter "Last Week In Pony". There are corresponding commands for each.
+
+- publish-release-notes-to-github.bash
+- send-announcement-to-pony-zulip.bash
+- add-announcement-to-last-week-in-pony.bash
+
+In addition there are normal cleanup actions that need to be taken as part of the release process and should be done after all announcements are done.
+
+- rotate-release-notes.bash
+
+Any project that uses release notes needs to run this command as part of post-announcement cleanup.
+
+- delete-announcement-tag.bash
+
+All projects should run this command to clean up the tag used to trigger the announce-a-release step. `delete-announcement-tag.bash` should be run after all other announcement commands have been run as they all depend on the `announce-X.Y.Z` existing.
 
 **announce-a-release.yml**:
 
@@ -205,23 +217,57 @@ on:
     tags: announce-\d+.\d+.\d+
 
 jobs:
-  announce-a-release:
-    name: Announce a release
+  announce:
+    name: Announcements
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout main
+        uses: actions/checkout@v2
         with:
           ref: "main"
           token: ${{ secrets.RELEASE_TOKEN }}
-      - name: Announce
+      - name: Release notes
         uses: ponylang/release-bot-action@0.5.0
         with:
-          entrypoint: announce-a-release.bash
-          git_user_name: "Ponylang Main Bot"
-          git_user_email: "ponylang.main@gmail.com"
+          entrypoint: publish-release-notes-to-github.bash
         env:
           RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+      - name: Zulip
+        uses: ponylang/release-bot-action@0.5.0
+        with:
+          entrypoint: send-announcement-to-pony-zulip.bash
+        env:
           ZULIP_TOKEN: ${{ secrets.ZULIP_TOKEN }}
+      - name: Last Week in Pony
+        uses: ponylang/release-bot-action@0.5.0
+        with:
+          entrypoint: add-announcement-to-last-week-in-pony.bash
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+
+  post-announcement:
+    name: Tasks to run after the release has been announced
+    needs:
+      - announce
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+        with:
+          ref: "main"
+          token: ${{ secrets.RELEASE_TOKEN }}
+      - name: Rotate release notes
+        uses: ponylang/release-bot-action@0.5.0
+        with:
+          entrypoint: rotate-release-notes.bash
+          git_user_name: "Ponylang Main Bot"
+          git_user_email: "ponylang.main@gmail.com"
+      - name: Delete announcement trigger tag
+        uses: ponylang/release-bot-action@0.5.0
+        with:
+          entrypoint: delete-announcement-tag.bash
+          git_user_name: "Ponylang Main Bot"
+          git_user_email: "ponylang.main@gmail.com"
 ```
 
 **N.B.** The environment variable `RELEASE_TOKEN` that is required by each step **must** be a personal access token with `public_repo` access. You can not use the `GITHUB_TOKEN` environment variable provided by GitHub's action environment. If you try to use `GITHUB_TOKEN`, no additional steps will trigger after start-a-release has completed.

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

@@ -0,0 +1,87 @@
+#!/bin/bash
+
+# Adds a note about a release to the Last Week in Pony newsletter
+#
+# Tools required in the environment that runs this:
+#
+# - bash
+# - curl
+# - jq
+
+set -o errexit
+
+# Verify ENV is set up correctly
+# We validate all that need to be set in case, in an absolute emergency,
+# we need to run this by hand. Otherwise the GitHub actions environment should
+# provide all of these if properly configured
+if [[ -z "${GITHUB_REF}" ]]; then
+  echo -e "\e[31mThe release tag needs to be set in GITHUB_REF."
+  echo -e "\e[31mThe tag should be in the following GitHub specific form:"
+  echo -e "\e[31m    /refs/tags/announce-X.Y.Z"
+  echo -e "\e[31mwhere X.Y.Z is the version we are announcing"
+  echo -e "\e[31mExiting.\e[0m"
+  exit 1
+fi
+
+if [[ -z "${GITHUB_REPOSITORY}" ]]; then
+  echo -e "\e[31mName of this repository needs to be set in GITHUB_REPOSITORY."
+  echo -e "\e[31mShould be in the form OWNER/REPO, for example:"
+  echo -e "\e[31m     ponylang/ponyup"
+  echo -e "\e[31mExiting.\e[0m"
+  exit 1
+fi
+
+if [[ -z "${RELEASE_TOKEN}" ]]; then
+  echo -e "\e[31mA personal access token with 'public repo' access"
+  echo -e "needs to be set in RELEASE_TOKEN."
+  echo -e "Exiting.\e[0m"
+  exit 1
+fi
+
+# no unset variables allowed from here on out
+# allow above so we can display nice error messages for expected unset variables
+set -o nounset
+
+# Extract version from tag reference
+# Tag ref version: "refs/tags/announce-1.0.0"
+# Version: "1.0.0"
+VERSION="${GITHUB_REF/refs\/tags\/announce-/}"
+
+# Update Last Week in Pony
+echo -e "\e[34mAdding release to Last Week in Pony...\e[0m"
+
+result=$(curl https://api.github.com/repos/ponylang/ponylang-website/issues?labels=last-week-in-pony)
+
+lwip_url=$(echo "${result}" | jq -r '.[].url')
+if [ "$lwip_url" != "" ]; then
+  body="
+Version ${VERSION} of ${GITHUB_REPOSITORY} has been released.
+See the [release notes](https://github.com/${GITHUB_REPOSITORY}/releases/tag/${VERSION}) for more details.
+"
+
+  jsontemplate="
+  {
+    \"body\":\$body
+  }
+  "
+
+  json=$(jq -n \
+  --arg body "$body" \
+  "${jsontemplate}")
+
+  result=$(curl -s -X POST "$lwip_url/comments" \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    -u "${RELEASE_TOKEN}" \
+    --data "${json}")
+
+  rslt_scan=$(echo "${result}" | jq -r '.id')
+  if [ "$rslt_scan" != null ]; then
+    echo -e "\e[34mRelease notice posted to LWIP\e[0m"
+  else
+    echo -e "\e[31mUnable to post to LWIP, here's the curl output..."
+    echo -e "\e[31m${result}\e[0m"
+  fi
+else
+  echo -e "\e[31mUnable to post to Last Week in Pony."
+  echo -e "Can't find the issue.\e[0m"
+fi