Add docs workflow to CI

Author: ernestognw

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Build Docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up environment
+        uses: ./.github/actions/setup
+      - run: bash scripts/git-user-config.sh
+      - run: node scripts/update-docs-branch.js
+      - run: git push --all origin .

docs/antora.yml

@@ -1,6 +1,6 @@
 name: community-contracts
 title: Community Contracts
-version: 0.0.0-alpha.0
+version: 0.0.1
 prerelease: true
 nav:
   - modules/ROOT/nav.adoc

scripts/git-user-config.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -euo pipefail -x
+
+git config user.name 'github-actions'
+git config user.email '41898282+github-actions[bot]@users.noreply.github.com'

scripts/update-docs-branch.js

@@ -0,0 +1,68 @@
+const proc = require('child_process');
+const read = cmd => proc.execSync(cmd, { encoding: 'utf8' }).trim();
+const run = cmd => {
+  proc.execSync(cmd, { stdio: 'inherit' });
+};
+const tryRead = cmd => {
+  try {
+    return read(cmd);
+  } catch {
+    return undefined;
+  }
+};
+
+// The community contracts currently don't have a defined release process.
+// The master branch is used for development, and the docs are updated from there.
+// Use /^release-v(?<version>(?<major>\d+)\.(?<minor>\d+)(?:\.(?<patch>\d+))?)$/ for a release branch
+const masterBranch = /^master$/;
+
+const currentBranch = read('git rev-parse --abbrev-ref HEAD');
+const match = currentBranch.match(masterBranch);
+
+if (!match) {
+  console.error('Not currently on master branch');
+  process.exit(1);
+}
+
+const pkgVersion = require('../package.json').version;
+
+if (pkgVersion.includes('-') && !pkgVersion.includes('.0.0-')) {
+  console.error('Refusing to update docs: non-major prerelease detected');
+  process.exit(0);
+}
+
+const current = match.groups;
+const docsBranch = `docs-v${current?.major ?? pkgVersion.split('.')[0]}.x`;
+
+// Fetch remotes and find the docs branch if it exists
+run('git fetch --all --no-tags');
+const matchingDocsBranches = tryRead(`git rev-parse --glob='*/${docsBranch}'`);
+
+if (!matchingDocsBranches) {
+  // Create the branch
+  run(`git checkout --orphan ${docsBranch}`);
+} else {
+  const [publishedRef, ...others] = new Set(matchingDocsBranches.split('\n'));
+  if (others.length > 0) {
+    console.error(
+      `Found conflicting ${docsBranch} branches.\n` +
+        'Either local branch is outdated or there are multiple matching remote branches.',
+    );
+    process.exit(1);
+  }
+  const publishedVersion = JSON.parse(read(`git show ${publishedRef}:package.json`)).version;
+  const publishedMinor = publishedVersion.match(/\d+\.(?<minor>\d+)\.\d+/).groups.minor;
+  if (current.minor < publishedMinor) {
+    console.error('Refusing to update docs: newer version is published');
+    process.exit(0);
+  }
+
+  run('git checkout --quiet --detach');
+  run(`git reset --soft ${publishedRef}`);
+  run(`git checkout ${docsBranch}`);
+}
+
+run('npm run prepare-docs');
+run('git add -f docs'); // --force needed because generated docs files are gitignored
+run('git commit -m "Update docs"');
+run(`git checkout ${currentBranch}`);