Add workflow to update getting started guide

This change adds an automated workflow to open a pull request to update the
version in the getting started guide when a release is made.

Signed-off-by: Austin Vazquez <[email protected]>

Author: austinvazquez

.github/workflows/update-getting-started-guide.yml

@@ -0,0 +1,79 @@
+name: Update getting started guide
+
+on:
+  release:
+    types: ['released']
+  pull_request:
+    branches: ['main', 'release/**']
+    paths:
+      # Run workflow on changes to the workflow definition itself to spot check
+      # the core version update functionality.
+      - '.github/workflows/update-getting-started-guide.yml'
+      - 'scripts/update-getting-started-guide-version.sh'
+      # Run workflow on changes to the getting started guide to validate
+      # changes to the documentation do not break the update workflow.
+      - 'docs/getting-started.md'
+
+jobs:
+  test-update-version:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-20.04
+
+    permissions:
+      contents: read
+      pull-requests: read
+
+    env:
+      RELEASE_TAG: ''
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            docs/getting-started.md
+            scripts/update-getting-started-guide-version.sh
+
+      - name: Mock release tag on pull request
+        run: echo "RELEASE_TAG=v0.0.0-${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+
+      - name: Test update getting started version
+        run: bash scripts/update-getting-started-guide-version.sh --assert ${{ env.RELEASE_TAG }}
+
+  update-version:
+    if: github.event_name == 'release'
+    runs-on: ubuntu-20.04
+
+    permissions:
+      # Write permissions needed to create pull request.
+      # Risk is mitigated by seperating jobs such that workflows
+      # running with write permissions only use code from main.
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          sparse-checkout: |
+            docs/getting-started.md
+            scripts/update-getting-started-guide-version.sh
+
+      - name: Update getting started version
+        run: bash scripts/update-getting-started-guide-version.sh --verbose ${{ github.event.release.tag_name }}
+
+      - name: Create PR
+        uses: peter-evans/create-pull-request@v6
+        with:
+          title: 'Update getting started to ${{ github.event.release.tag_name }}'
+          commit-message: 'Update getting started to ${{ github.event.release.tag_name }}'
+          body: |
+            This PR must be closed and reopened manually to trigger automated checks.
+
+            Auto-generated by [create-pull-request](https://github.com/peter-evans/create-pull-request).
+          labels: easy-to-review, automated-pr
+          token: ${{ secrets.GITHUB_TOKEN }}
+          author: "GitHub <[email protected]>"
+          signoff: true
+          branch: 'create-pull-request/update-getting-started-version-to-${{ github.event.release.tag_name }}'
+          base: main
+          delete-branch: true

scripts/update-getting-started-guide-version.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+#   Copyright The Soci Snapshotter Authors.
+
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+
+#       http://www.apache.org/licenses/LICENSE-2.0
+
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+# A script to assert version in the getting started guide was updated
+# correctly by GitHub Actions workflow.
+#
+# Usage: bash update-getting-started-guide-version.sh [-a|--assert] [-v|--verbose] <RELEASE_TAG>
+
+set -eux -o pipefail
+
+tag=$1
+
+ASSERT=false
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --assert|-a)
+      ASSERT=true
+      shift # past argument
+      ;;
+    --verbose|-v)
+      VERBOSE=true
+      shift # past argument
+      ;;
+    --*|-*)
+      echo "Unknown option $1"
+      exit 1
+      ;;
+    *)
+      tag=$1
+      shift # past argument
+      ;;
+  esac
+done
+
+# Strip 'v' prefix from tag if not already stripped.
+VERSION=${tag/v/} 
+
+assert_diff() {
+  local diff_output
+  # Disable warning for A && B || C is not if-then-else; C may run when A is true.
+  # Branch B contains exit, so C will not run when A and B branches fail.
+  # This is intended to have the assertion fail if the diff is empty.
+  # shellcheck disable=SC2015
+  diff_output=$(git diff --exit-code) && {
+    echo "Error: no changes made; expected getting started version to be updated to \"${VERSION}\"" && exit 1
+  } || {
+    if [[ "${diff_output}" == *"+version=\"${VERSION}\""* ]]; then
+      echo "Diff looks good!"
+    else
+      echo "Error: release version not set properly" && exit 1
+    fi
+  }
+}
+
+sed -i -E "s/version=\"([0-9]+\.){2}[0-9]+\"/version=\"${VERSION}\"/" docs/getting-started.md
+
+[ $VERBOSE = true ] && git diff
+[ $ASSERT = true ] && assert_diff