Update cached state conditions and docs (#4332)

.github/workflows/test.yml

@@ -14,12 +14,12 @@ on:
       regenerate-disks:
         type: boolean
         default: false
-        description: 'Just update stateful disks'
+        description: 'Just update mandatory checkpoint disks'
         required: true
       run-full-sync:
         type: boolean
         default: false
-        description: 'Just trigger a full sync'
+        description: 'Just run a full sync and update tip disks'
         required: true
 
   pull_request:
@@ -99,7 +99,8 @@ jobs:
       zebra_skip_ipv6_tests: '1'
       rust_log: info
 
-  # Run all the zebra tests, including tests that are ignored by default
+  # Run all the zebra tests, including tests that are ignored by default.
+  # Skips tests that need a cached state disk or a lightwalletd binary.
   test-all:
     name: Test all
     runs-on: ubuntu-latest
@@ -175,6 +176,10 @@ jobs:
         env:
           ZEBRA_TEST_LIGHTWALLETD: '1'
 
+  # Regenerate mandatory checkpoint disks.
+  # Runs:
+  # - on every PR update, but only if Zebra's state version changes in the PR
+  # - on request
   regenerate-stateful-disks:
     needs: [ build, changed-files]
     uses: ./.github/workflows/gcp-test-deploy.yml
@@ -189,7 +194,7 @@ jobs:
       disk_suffix: checkpoint
       height_grep_text: 'flushing database to disk height=Height'
 
-  # Test that Zebra syncs and fully validates a few thousand blocks from a cached post-checkpoint state
+  # Test that Zebra syncs and fully validates a few thousand blocks from a cached mandatory checkpoint disk
   test-stateful-sync:
     needs: build
     uses: ./.github/workflows/gcp-test-deploy.yml
@@ -202,14 +207,18 @@ jobs:
       saves_to_disk: false
       disk_suffix: checkpoint
 
-  # Test that Zebra can run a full mainnet sync after a PR is approved
+  # Test that Zebra can run a full mainnet sync and regenerate tip disks.
+  # Runs:
+  # - after every PR is merged to `main`
+  # - on every PR update, but only if Zebra's state version changes in the PR
+  # - on request
   test-full-sync:
     needs: build
     uses: ./.github/workflows/gcp-test-deploy.yml
     # TODO change `github.ref_name == 'main'` to `startsWith(github.head_ref, 'mergify/merge-queue/')`
     # to only run on Mergify head branches, and on manual dispatch:
     # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#running-your-workflow-based-on-the-head-or-base-branch-of-a-pull-request-1
-    if: ${{ github.event_name == 'push' || github.event.inputs.run-full-sync == 'true' || github.event.inputs.regenerate-disks != 'true'}}
+    if: ${{ (github.event_name == 'push' && github.ref_name == 'main') || (needs.changed-files.outputs.rebuild == 'true' && github.event_name == 'push') || github.event.inputs.run-full-sync == 'true' }}
     with:
       test_id: full-sync-to-tip
       test_description: Test a full sync up to the tip