Add workflow to generate and update docs branches

(cherry picked from commit 7c47ac7)

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Build Docs
+
+on:
+  push:
+    branches: [release-v*]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 12.x
+      - uses: actions/cache@v2
+        id: cache
+        with:
+          path: '**/node_modules'
+          key: npm-v2-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-v2-
+      - run: npm ci
+        if: steps.cache.outputs.cache-hit != 'true'
+      - run: bash scripts/git-user-config.sh
+      - run: node scripts/update-docs-branch.js
+      - run: git push --all origin 

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,55 @@
+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 (e) { return undefined; } };
+
+const releaseBranchRegex = /^release-v(?<version>(?<major>\d+)\.(?<minor>\d+)(?:\.(?<patch>\d+))?)$/;
+
+const currentBranch = read(`git rev-parse --abbrev-ref HEAD`);
+const match = currentBranch.match(releaseBranchRegex);
+
+if (!match) {
+  console.error(`Not currently on a release branch`);
+  process.exit(1);
+}
+
+if (/-.*$/.test(require('../package.json').version)) {
+  console.error(`Refusing to update docs: prerelease detected`);
+  process.exit(0);
+}
+
+const current = match.groups;
+const docsBranch = `docs-v${current.major}.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}`);