From 70a44bca09adc6c317e9c872a7362ba3be8bfb17 Mon Sep 17 00:00:00 2001
From: Javier Maestro <jjmaestro@ieee.org>
Date: Wed, 20 Nov 2024 12:24:26 +0000
Subject: [PATCH] refactor: pages.yaml

* Add pre-commit linting and validation
* Auto-generate the strategy matrix
* Move Bazelisk and mdBook versions to `env` so that it's easier to
  test and upgrade to new versions.
* `fail-fast: false` so that when one of the matrix jobs fails so that
  we can see failures for all of the jobs (easier to debug and the jobs
  are lightweight so it's not too costly).
* Simplify the patching of old branches
* Make steps easier to read, shortening lines and adding whitespace
---
 .github/workflows/pages.yaml | 253 +++++++++++++++++++++++------------
 .pre-commit-config.yaml      |  23 ++++
 2 files changed, 188 insertions(+), 88 deletions(-)

diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml
index e9ca9f7f..8547705c 100644
--- a/.github/workflows/pages.yaml
+++ b/.github/workflows/pages.yaml
@@ -1,6 +1,7 @@
 name: Generate docs
+
 on:
-  pull_request: 
+  pull_request:
     branches:
       - main
     paths:
@@ -9,112 +10,188 @@ on:
   push:
     branches:
       - main
+
+env:
+  BAZELISK_VERSION: 1.23.0
+  MDBOOK_VERSION: 0.4.42
+
+  GH_REPO: ${{ github.repository }}
+  MIN_VERSION: ${{ github.event.inputs.MIN_VERSION || '0.1.0' }}
+  FILTER_VERSION: ${{ github.event.inputs.FILTER_VERSION || '' }}
+  RELEASE_TAG_REGEX: ^\d+\.\d+\.\d+$
+
 jobs:
-  pages:
+  setup:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        # Create a job for release
-        include:
-          - ref: main
-          - ref: "0.12.0"
-          - ref: "0.11.1"
-          - ref: "0.11.0"
-          - ref: "0.10.1"
-          - ref: "0.9.0"
-          - ref: "0.8.0"
-          - ref: "0.7.1"
-          - ref: "0.7.0"
-          - ref: "0.6.0"
-          - ref: "0.5.1"
-          - ref: "0.5.0"
-          - ref: "0.4.0"
-          - ref: "0.3.0"
-          - ref: "0.2.0"
-          - ref: "0.1.0"
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
     steps:
-      - uses: actions/checkout@v2
-        if: ${{ matrix.ref == 'main' }}
-      - uses: actions/checkout@v2
+      - name: get release tags that match $release_tag_regex
+        id: get_release_tags
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          RELEASES_JSON="$(
+            curl -s --fail-with-body \
+              -H "Authorization: token $GH_TOKEN" \
+              "https://api.github.com/repos/$GH_REPO/tags"
+          )"
+
+          RELEASES_JSON_FILTERED="$(echo "$RELEASES_JSON" |
+            jq -c \
+              --arg RELEASE_TAG_REGEX "$RELEASE_TAG_REGEX" \
+              --arg FILTER_VERSION "$FILTER_VERSION" \
+              --arg MIN_VERSION "$MIN_VERSION" '
+              [ "main" ] +
+              ([.[].name |
+                 select(
+                   (test($RELEASE_TAG_REGEX) and
+                    (. | split(".") | map(tonumber) >= ($MIN_VERSION | split(".") | map(tonumber)))
+                   ) and ($FILTER_VERSION == "" or . == $FILTER_VERSION)
+                 )
+              ])
+              '
+          )"
+          echo "releases=$RELEASES_JSON_FILTERED"
+          echo "releases=$RELEASES_JSON_FILTERED" >> "$GITHUB_OUTPUT"
+
+    outputs:
+      releases: ${{ steps.get_release_tags.outputs.releases || '[]' }}
+
+  build:
+    runs-on: ubuntu-latest
+    needs: setup
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ref: ${{ fromJson(needs.setup.outputs.releases) }}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+      BIN: ${{ github.workspace }}/bin
+
+    steps:
+      - name: Checkout $REF
+        uses: actions/checkout@v4
         with:
           ref: ${{ matrix.ref }}
-        if: ${{ matrix.ref != 'main' }}
-      - name: Pin the release to main
-        run: echo "RELEASE=main" >> $GITHUB_ENV
-        if: ${{ matrix.ref == 'main' }}
-      - name: Patch older branches
+
+      - name: Patch $REF
+        env:
+          REF: ${{ matrix.ref }}
         run: |
-          ref="${{ matrix.ref }}"
+          [[ "$REF" == "main" ]] && exit
 
-          [[ "$ref" == "main" ]] && exit
+          PATCH=".github/docs-${REF}.patch"
 
-          v_major="$(echo "$ref" | cut -d. -f1)"
-          v_minor="$(echo "$ref" | cut -d. -f2)"
-          v_patch="$(echo "$ref" | cut -d. -f3)"
+          URL="https://raw.githubusercontent.com/$GH_REPO/main/$PATCH"
+          echo "$URL"
 
-          [[ $v_minor -gt 10 ]] && exit
+          curl -LO --fail-with-body "$URL" || {
+              echo "No patch found for $REF, exiting..."
+              exit 0
+          }
+
+          echo "Patching ref: $REF"
+          git apply "$(basename "$PATCH")"
 
-          mkdir -p ${{ github.workspace }}/.github
-          curl https://raw.githubusercontent.com/bazel-contrib/rules_foreign_cc/main/.github/docs-${{ matrix.ref }}.patch > ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
-          git apply ${{ github.workspace }}/.github/docs-${{ matrix.ref }}.patch
       - name: Install bazelisk
         run: |
-          curl -LO "https://github.com/bazelbuild/bazelisk/releases/download/v1.9.0/bazelisk-linux-amd64"
-          mkdir -p "${{ github.workspace }}/bin/"
-          mv bazelisk-linux-amd64 "${{ github.workspace }}/bin/bazel"
-          chmod +x "${{ github.workspace }}/bin/bazel"
-      - name: Generate docs
-        run: |
-          "${{ github.workspace }}/bin/bazel" run //:generate_docs
-          "${{ github.workspace }}/bin/bazel" clean
-        working-directory: ${{ github.workspace }}/docs
+          BAZELISK="bazelisk-linux-amd64"
+
+          URL="https://github.com/bazelbuild/bazelisk/releases/download/v$BAZELISK_VERSION/$BAZELISK"
+          echo "URL=$URL"
+          curl -LO --fail-with-body "$URL"
+
+          chmod +x "$BAZELISK"
+
+          mkdir -p "$BIN"
+          mv "$BAZELISK" "$BIN/bazel"
+
       - name: Install mdbook
         run: |
-          curl -LO "https://github.com/rust-lang/mdBook/releases/download/v0.4.10/mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir -p "${{ github.workspace }}/bin/"
-          tar -xvf mdbook-v0.4.10-x86_64-unknown-linux-gnu.tar.gz
-          mv mdbook "${{ github.workspace }}/bin/mdbook"
-          chmod +x "${{ github.workspace }}/bin/mdbook"
-      - name: mdbook build
-        run: ${{ github.workspace }}/bin/mdbook build
+          MDBOOK="mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz"
+
+          URL="https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/$MDBOOK"
+          echo "URL=$URL"
+          curl -LO --fail-with-body "$URL"
+
+          tar -xvf "$MDBOOK"
+          chmod +x mdbook
+
+          mkdir -p "$BIN"
+          mv mdbook "$BIN/mdbook"
+
+      - name: bazel run //:generate_docs
+        run: |
+          "$BIN/bazel" run //:generate_docs
         working-directory: ${{ github.workspace }}/docs
-      - name: Save the newly built book
+
+      - name: mdbook build root
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs/root
+        if: ${{ matrix.ref == 'main' }}
+
+      - name: mdbook build docs
+        run: |
+          "$BIN/mdbook" build
+        working-directory: ${{ github.workspace }}/docs
+
+      - name: Upload docs root
         uses: actions/upload-artifact@v4
         with:
-          name: "${{ matrix.ref }}"
+          name: ${{ matrix.ref }}-root
+          path: ${{ github.workspace }}/docs/root/book
+          if-no-files-found: error
+        if: ${{ github.event_name != 'pull_request' && matrix.ref == 'main' }}
+
+      - name: Upload docs/book
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.ref }}
           path: ${{ github.workspace }}/docs/book
           if-no-files-found: error
         if: ${{ github.event_name != 'pull_request' }}
-      - name: Build root
-        run: ${{ github.workspace }}/bin/mdbook build
-        if: ${{ matrix.ref == 'main' }}
-        working-directory: ${{ github.workspace }}/docs/root
-      - name: Save the newly built book
-        uses: actions/upload-artifact@v4
-        with:
-          name: "${{ matrix.ref }}-root"
-          path: ${{ github.workspace }}/docs/root/book
-          if-no-files-found: error
-        if: ${{ matrix.ref == 'main' && github.event_name != 'pull_request' }}
-  publish:
-    needs: pages
-    if: ${{ github.event_name != 'pull_request' }}
+
+  deploy:
     runs-on: ubuntu-latest
+    needs: build
+    if: ${{ github.event_name != 'pull_request' }}
+
+    defaults:
+      run:
+        shell: bash --noprofile --norc -euo pipefail {0}
+
+    env:
+      WORKSPACE: ${{ github.workspace }}
+
     steps:
-    - name: Fetch artifacts (first root then others so the ordering is correct)
-      uses: actions/download-artifact@v2
-      with:
-        name: main-root
-        path: ${{ github.workspace }}/docs/book
-    - name: Fetch artifacts (first root then others so the ordering is correct)
-      uses: actions/download-artifact@v2
-      with:
-        path: ${{ github.workspace }}/docs/pages
-    - name: Install pages
-      run: mv ${{ github.workspace }}/docs/pages/* ${{ github.workspace }}/docs/book/
-    - name: publish
-      uses: peaceiris/actions-gh-pages@v3
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_branch: docs
-        publish_dir: ./docs/book
+      - name: Fetch artifacts (first root)
+        uses: actions/download-artifact@v4
+        with:
+          name: main-root
+          path: ${{ github.workspace }}/docs/book
+
+      - name: Fetch artifacts (then others)
+        uses: actions/download-artifact@v4
+        with:
+          path: ${{ github.workspace }}/docs/pages
+
+      - name: Install pages
+        run: mv "$WORKSPACE/docs/pages/"* "$WORKSPACE/docs/book/"
+
+      - name: publish
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: docs
+          publish_dir: ./docs/book
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5d4771d2..1138888d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -2,6 +2,11 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+
   - repo: https://github.com/keith/pre-commit-buildifier
     rev: 6.1.0.1
     hooks:
@@ -11,3 +16,21 @@ repos:
           - --warnings=all
       - id: buildifier-lint
         args: *args
+
+  - repo: https://github.com/mpalmer/action-validator
+    rev: v0.6.0
+    hooks:
+      - id: action-validator
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.4
+    hooks:
+      - id: actionlint
+        files: >-
+          (?x)^(
+            .github/workflows/pages.yaml
+          )$