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
2024-11-20 12:24:26 +00:00 · 2024-11-20 12:24:26 +00:00 · 70a44bca09
parent 252753585f
commit 70a44bca09
2 changed files with 188 additions and 88 deletions
--- a/.github/workflows/pages.yaml
+++ b/.github/workflows/pages.yaml
@ -1,4 +1,5 @@
 name: Generate docs
+
 on:
  pull_request:
    branches:
@ -9,111 +10,187 @@ 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
+      - name: Fetch artifacts (first root)
+        uses: actions/download-artifact@v4
        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
+
+      - name: Fetch artifacts (then others)
+        uses: actions/download-artifact@v4
        with:
          path: ${{ github.workspace }}/docs/pages
+
      - name: Install pages
-      run: mv ${{ github.workspace }}/docs/pages/* ${{ github.workspace }}/docs/book/
+        run: mv "$WORKSPACE/docs/pages/"* "$WORKSPACE/docs/book/"
+
      - name: publish
-      uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: docs
--- 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
+          )$