From 028a5c1fe9b07f22e26cd3a012dae35b2fa35bd6 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Wed, 11 Dec 2024 12:56:29 -0800
Subject: [PATCH] chore(cd): automate release tagging (#745)

---
 .github/workflows/release.yml | 10 +++++++-
 .github/workflows/tag.yaml    | 43 +++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md               | 23 ++++++++++++++++---
 3 files changed, 72 insertions(+), 4 deletions(-)
 create mode 100644 .github/workflows/tag.yaml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b17f96ae..94fc383b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,13 +2,21 @@
 name: Release
 
 on:
+  # Can be triggered from the tag.yaml workflow
+  workflow_call:
+    inputs:
+      tag_name:
+        required: true
+        type: string
+  # Or, developers can manually push a tag from their clone
   push:
     tags:
       - "v*.*.*"
 
 jobs:
   release:
-    uses: bazel-contrib/.github/.github/workflows/release_ruleset.yaml@v5
+    uses: bazel-contrib/.github/.github/workflows/release_ruleset.yaml@c9d6d1893b10a8d68584a6ba52c3dd35506486d0 # 2024-12-03
     with:
       release_files: rules_oci-*.tar.gz
       prerelease: false
+      tag_name: ${{ inputs.tag_name }}
diff --git a/.github/workflows/tag.yaml b/.github/workflows/tag.yaml
new file mode 100644
index 00000000..bd23df7d
--- /dev/null
+++ b/.github/workflows/tag.yaml
@@ -0,0 +1,43 @@
+# Tag a new release using https://github.com/marketplace/actions/conventional-commits-versioner-action
+#
+# This is easier than having to run manual `git` operations on a local clone.
+# It also runs on a schedule so we don't leave commits unreleased indefinitely
+# (avoiding users having to ping "hey could someone cut a release").
+
+name: Tag a Release
+on:
+  # Allow devs to tag manually through the GitHub UI.
+  # For example after landing a fix that customers are waiting for.
+  workflow_dispatch:
+
+  # Run twice a month, on the 12th and 27th at 3PM UTC (8AM PST)
+  # This is a trade-off between making too many releases,
+  # which overwhelms BCR maintainers and over-notifies users,
+  # and releasing too infrequently which delays delivery of bugfixes and features.
+  schedule:
+    - cron: "0 15 12,27 * *"
+
+jobs:
+  tag:
+    permissions:
+      contents: write # allow create tag
+    runs-on: ubuntu-latest
+    outputs:
+      new-tag: ${{ steps.ccv.outputs.new-tag }}
+      new-tag-version: ${{steps.ccv.outputs.new-tag-version}}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Need enough history to find the prior release tag
+          fetch-depth: 0
+      - name: Bump tag if necessary
+        id: ccv
+        uses: smlx/ccv@7318e2f25a52dcd550e75384b84983973251a1f8 # v0.10.0
+  release:
+    needs: tag
+    uses: ./.github/workflows/release.yml
+    with:
+      tag_name: ${{ needs.tag.outputs.new-tag-version }}
+    if: needs.tag.outputs.new-tag == 'true' && needs.tag.outputs.new-tag-version-type != 'major'
+    permissions:
+      contents: write # allow create release
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 066fcb63..9047966c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,23 @@ This means that any usage of `@rules_oci` on your system will point to this fold
 
 ## Releasing
 
-1. Determine the next release version, following semver (could automate in the future from changelog)
-1. Tag the repo and push it
-1. Watch the automation run on GitHub actions
+Releases are automated on a cron trigger.
+The new version is determined automatically from the commit history, assuming the commit messages follow conventions, using
+https://github.com/marketplace/actions/conventional-commits-versioner-action.
+If you do nothing, eventually the newest commits will be released automatically as a patch or minor release.
+This automation is defined in .github/workflows/tag.yaml.
+
+Rather than wait for the cron event, you can trigger manually. Navigate to
+https://github.com/bazel-contrib/rules_oci/actions/workflows/tag.yaml
+and press the "Run workflow" button.
+
+If you need control over the next release version, for example when making a release candidate for a new major,
+then: tag the repo and push the tag, for example
+
+```sh
+% git fetch
+% git tag v1.0.0-rc0 origin/main
+% git push origin v1.0.0-rc0
+```
+
+Then watch the automation run on GitHub actions which creates the release.