Address review: Crosslink Finality terminology, operator definitions, bounded availability semantics, divergences appendix

.github/actions/render/action.yml

@@ -1,7 +1,29 @@
-name: Render ZIPs and Zcash Protocol Specification
-description: GitHub Action to compile ZIPs and Zcash Protocol Specification LaTeX documents
-author: Deirdre Connolly
+name: Render All
+description: GitHub Action to compile ZIPs and the protocol specification.
+author: Deirdre Connolly and Daira-Emma Hopwood
 runs:
-  using: docker
-  # Runs `make all` or something like it
-  image: ../../../Dockerfile
+  using: composite
+  steps:
+    - uses: DeterminateSystems/nix-installer-action@c5a866b6ab867e88becbed4467b93592bce69f8a # v21
+
+    - name: Restore Nix store cache
+      id: nix-cache
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+      with:
+        path: /tmp/nix-closure
+        key: nix-devshell-${{ runner.os }}-${{ hashFiles('flake.lock', 'flake.nix') }}
+
+    - name: Import cached Nix store paths
+      if: steps.nix-cache.outputs.cache-hit == 'true'
+      shell: bash
+      run: nix-store --import < /tmp/nix-closure/store.nar
+
+    - shell: bash
+      run: nix develop --profile /tmp/dev-profile --command make all
+
+    - name: Export Nix store for caching
+      if: steps.nix-cache.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        mkdir -p /tmp/nix-closure
+        nix-store --export $(nix-store -qR /tmp/dev-profile) > /tmp/nix-closure/store.nar

.github/workflows/publish.yaml

@@ -0,0 +1,87 @@
+name: Deploy Rendered Site
+
+on:
+  push:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. However, do NOT cancel in-progress runs as we
+# want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  render-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: publish
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Verify nonexistence of `base_ref`
+        shell: bash
+        run: |
+          if [ -e base_ref ]; then exit 1; fi
+
+      - name: Set base ref
+        run: |
+          git show --format=%H --no-notes --no-patch 'HEAD' -- |tee base_ref
+          if ! ( grep -E '^[0-9a-f]{40}$' base_ref ); then exit 1; fi
+
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Merge `main` to the `publish` branch
+        run: |
+          set -x
+          git config --global user.name 'github_actions'
+          git config --global user.email 'actions@github.com'
+          version="$(git describe --tags --abbrev=6 origin/main |sed 's/-1-g.*//')"
+          # Merge preferring the version in main.
+          git merge -s recursive -Xtheirs origin/main --commit -m 'Auto-deploy: merging "main" branch'
+          # Apply a tag to the merge commit, otherwise the uses of `git describe` in `protocol/Makefile`
+          # won't find it. Any existing tag of the same name will be overwritten.
+          git tag -f "${version}-auto"
+
+      - name: Compile ZIPs and Zcash Protocol Specification
+        uses: ./.github/actions/render
+
+      - name: Set `.gitignore` to not ignore `rendered/`
+        # This needs to be afer rendering so that it is not considered to make the tree dirty.
+        run: sed -i 's@^rendered/$@@' .gitignore
+
+      - name: Commit and push to `publish` branch
+        uses: EndBug/add-and-commit@290ea2c423ad77ca9c62ae0f5b224379612c0321 # v10.0.0
+        with:
+          add: 'rendered'
+          default_author: github_actions
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: 'rendered'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/render.yml

@@ -1,25 +1,60 @@
-name: Build tex and rst
+name: Check Renderability
 
-on: 
-  workflow_dispatch:
-  push:
-    branches:
-    - main
+on:
+  pull_request:
 
 jobs:
-
   render:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4.1.7
-        with: 
-          token: ${{ secrets.CI_TOKEN }}
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 3
 
-      - name: Compile ZIPs and Zcash Protocol Specification
-        uses: ./.github/actions/render
+      - name: Verify nonexistence of `rendered` and `base_ref`
+        shell: bash
+        run: |
+          if [ -e rendered ]; then exit 1; fi
+          if [ -e base_ref ]; then exit 1; fi
 
-      - uses: EndBug/add-and-commit@v9.1.4
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+
+      - name: Restore Nix store cache
+        id: nix-cache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
-          add: 'protocol/*.pdf *.html'
-          default_author: github_actions
+          path: /tmp/nix-closure
+          key: nix-devshell-${{ runner.os }}-${{ hashFiles('flake.lock', 'flake.nix') }}
+
+      - name: Import cached Nix store paths
+        if: steps.nix-cache.outputs.cache-hit == 'true'
+        run: nix-store --import < /tmp/nix-closure/store.nar
+
+      - name: Compile ZIPs
+        run: nix develop --profile /tmp/dev-profile --command make all-zips
+
+      - name: Set base ref
+        run: |
+          git show --format=%H --no-notes --no-patch "HEAD~1" -- |tee base_ref
+          if ! ( grep -E '^[0-9a-f]{40}$' base_ref ); then exit 1; fi
+
+      - name: Compile Protocol Specification
+        run: nix develop --profile /tmp/dev-profile --command make all
+
+      - name: Export Nix store for caching
+        if: steps.nix-cache.outputs.cache-hit != 'true'
+        run: |
+          # Free up some space before creating the (possibly very large) store tarball.
+          df
+          dpkg-query -Wf '${Installed-Size}\t${Package}\n' | sort -rn 2>/dev/null | head -30
+          docker system prune --all --force || /bin/true
+          sudo apt-get -y remove --purge \
+            '^docker.*' '^microsoft-edge.*' azure-cli '^google-cloud-cli.*' '^google-chrome.*' \
+            firefox java-common '^llvm-.*' '^libllvm.*' '^libclang-.*' '^mysql-.*' powershell snapd
+          sudo apt-get -y autoremove --purge
+          dpkg-query -Wf '${Installed-Size}\t${Package}\n' | sort -rn 2>/dev/null | head -30
+          df
+          mkdir -p /tmp/nix-closure
+          nix-store --export $(nix-store -qR /tmp/dev-profile) > /tmp/nix-closure/store.nar

.github/workflows/report_updatecheck.yml

@@ -0,0 +1,49 @@
+name: Status of dependency check
+on:
+  workflow_run:
+    workflows: ["Check dependencies of rendered ZIPs"]
+    types: [completed]
+
+permissions:
+  actions: read # Needed to list artifacts
+  checks: write # Needed to post the status
+
+jobs:
+  post_status:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            const runId = context.payload.workflow_run.id;
+            let conclusion = context.payload.workflow_run.conclusion;
+            let title = 'Dependencies are incorrect or could not be checked';
+
+            if (conclusion === 'success') {
+               // Check if the "neutral-signal" artifact exists.
+               const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  run_id: runId,
+               });
+
+               if (artifacts.data.artifacts.some(a => a.name === 'neutral-signal')) {
+                 conclusion = 'neutral';
+                 title = 'Dependencies are correct but not up-to-date';
+               } else {
+                 title = 'Dependencies are correct and up-to-date';
+               }
+            }
+
+            await github.rest.checks.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'Dependency check result',
+              head_sha: context.payload.workflow_run.head_sha,
+              status: 'completed',
+              conclusion,
+              output: {
+                title,
+                summary: "See 'View details' on 'Check dependencies of rendered ZIPs' for more information."
+              }
+            });

.github/workflows/updatecheck.yml

@@ -0,0 +1,31 @@
+name: Check dependencies of rendered ZIPs
+
+on:
+  pull_request:
+
+jobs:
+  updatecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.2
+
+      - name: Check dependencies
+        shell: bash
+        run: |
+          set +e
+          ./update_check.sh
+          exitcode=$?
+          if [ "$exitcode" -eq 1 ]; then
+            touch neutral.signal
+          else
+            exit $exitcode
+          fi
+
+      - name: Record status
+        uses: actions/upload-artifact@v7
+        if: hashFiles('neutral.signal') != ''
+        with:
+          name: neutral-signal
+          path: neutral.signal
+          retention-days: 1

.gitignore

@@ -19,15 +19,18 @@
 *.swp
 *.save
 *.save.*
+*~
+*.html.temp
 
 .Makefile.uptodate
 .zipfilelist.*
 .draftfilelist.*
 
-protocol/aux/
-protocol/html/
-protocol/saplinghtml/
+MultiMarkdown-6
 
-protocol/heartwood.pdf
+base_ref
+protocol/aux/
 protocol/protocol.ver
-*~
+
+rendered/
+temp/