Update the buildkite pipeline to build a release on v* tags

.buildkite/pipeline.yaml

@@ -1,3 +1,15 @@
+x-yaml-aliases:
+  commands:
+    - &hugo_build_environment_setup |
+      # Install package dependencies
+      apk add nodejs npm git hugo
+      # Install the node dependencies necessary to build the spec
+      npm i
+      # Pull all git submodules, required for the hugo theme
+      git submodule update --init --recursive
+      # Pull current proposal information
+      npm run get-proposals
+
 steps:
   - label: ":snake: Build swagger definitions for matrix.org"
     command:
@@ -19,14 +31,7 @@ steps:
 
   - label: ":books: Build the spec"
     command:
-      # Install package dependencies
-      - apk add nodejs npm git hugo
-      # Install the node dependencies necessary to build the spec
-      - npm i
-      # Pull all git submodules, required for the hugo theme
-      - git submodule update --init --recursive
-      # Pull current proposal information
-      - npm run get-proposals
+      - *hugo_build_environment_setup
       # Build the spec, will build to './spec'
       # Set the baseURL as we're deploying to https://spec.matrix.org/unstable
       - hugo --baseURL "/unstable" -d "spec"
@@ -36,4 +41,22 @@ steps:
       - spec.tar.gz
     plugins:
       - docker#v3.7.0:
-          image: alpine
+          image: alpine
+
+  - label: ":rocket: Release the spec"
+    # Only execute this step on tags matching "vX.Y"
+    if: build.tag =~ /^v\d+\.\d+$$/
+    command:
+      - *hugo_build_environment_setup
+      # Generate a stable version of the spec
+      - scripts/prepare-spec-release.sh "$BUILDKITE_TAG" spec
+      # Package the build as an artefact, which will be downloaded by:
+      # https://github.com/matrix-org/buildkite-webhook-listener
+      - tar -czf spec-release.tar.gz spec
+    artifact_paths:
+      - spec-release.tar.gz
+    plugins:
+      - docker#v3.7.0:
+          image: alpine
+          mount-buildkite-agent: false
+          propogate-environment: true

scripts/prepare-spec-release.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+#
+# This script will generate a stable release build of the spec.
+# It assumes you have `hugo` set up and configured properly.
+#
+# Usage:
+#
+#   ./scripts/prepare-spec-release.sh v<Matrix global version number> <output directory>
+#
+# Example:
+#
+#   ./scripts/prepare-spec-release.sh v1.2.3 release/
+#
+# The released spec files will be available at <output directory>/<Matrix global version number>,
+# i.e ./release/v1.2.3/.
+#
+# This script is used by .buildkite/pipeline as part of building and releasing the spec.
+
+if [ $# -lt 2 ]; then
+  echo 1>&2 "$0: not enough arguments"
+  exit 2
+fi
+
+# Modify the build config to specify a stable release
+sed -i.bak -e 's/status = "unstable"/status = "stable"/' config.toml
+
+# Create a release.yaml file which is used to build the changelog entry
+tee changelogs/release.yaml <<EOF
+  tag: $1
+  date: $(date +"%B %d, %Y")
+EOF
+
+# Build the spec, and set the baseURL and output directory to the new release version,
+# which should match the tag name.
+hugo --baseURL "/$1" -d "$2/$1"
+
+# Restore the original config file state
+mv config.toml.bak config.toml
+
+echo "Spec release files are available in: $2/$1"