github: standardize workflow job naming and update comments for clarity

Author: ffranr

.github/workflows/main.yaml

@@ -16,19 +16,17 @@ defaults:
     shell: bash
 
 env:
-  # go needs absolute directories, using the $HOME variable doesn't work here.
+  # Go needs absolute directories; using the $HOME variable doesn't work here.
   GOPATH: /home/runner/work/go
 
   GO_VERSION: '1.24.9'
-  
+
   LITD_ITEST_BRANCH: 'master'
 
 jobs:
-  #######################
-  # sql model generation
-  #######################
+  # Validate generated SQL models stay in sync with queries.
   sqlc-check:
-    name: Sqlc check
+    name: SQLC Model Generation
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -46,8 +44,9 @@ jobs:
       - name: Generate sql models
         run: make sqlc-check
 
+  # Rebuild RPC stubs and REST annotations to detect drift.
   rpc-check:
-    name: RPC check
+    name: RPC Stub and REST Annotation Check
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -61,8 +60,9 @@ jobs:
       - name: Generate RPC stubs and check REST annotations
         run: make rpc-check
 
+  # Ensure go.mod and go.sum remain tidy.
   mod-check:
-    name: go mod check
+    name: Go Module Tidy Check
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -76,8 +76,9 @@ jobs:
       - name: Run go mod tidy
         run: make mod-check
 
+  # Confirm deterministic test vectors are up to date.
   test-vector-check:
-    name: test vector check
+    name: Test Vector Regeneration Check
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -91,8 +92,9 @@ jobs:
       - name: Run test vector creation check
         run: make test-vector-check
 
+  # Verify database migration numbering and versions.
   migration-check:
-    name: migration version check
+    name: Database Migration Version Check
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -101,11 +103,9 @@ jobs:
       - name: Run migration check
         run: make migration-check
 
-  ########################
-  # Compilation check.
-  ########################
+  # Build the codebase and docs examples to catch compilation regressions.
   compile-check:
-    name: Compilation check
+    name: Code and Docs Compilation
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -122,11 +122,9 @@ jobs:
       - name: Compile docs examples
         run: make build-docs-examples
 
-  ########################
-  # sample configuration check
-  ########################
+  # Guard sample-tapd.conf defaults against accidental drift.
   sample-conf-check:
-    name: sample configuration check
+    name: Sample Config Defaults
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -140,11 +138,9 @@ jobs:
       - name: check default values in sample-tapd.conf file
         run: make sample-conf-check
 
-  ########################
-  # Docker build check.
-  ########################
+  # Smoke test Docker builds for default and dev images.
   docker-build-check:
-    name: Docker build check
+    name: Docker Build Smoke Tests
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -167,11 +163,9 @@ jobs:
           file: dev.Dockerfile
           tags: 'dev-taproot-assets'
 
-  ########################
-  # cross compilation
-  ########################
+  # Cross-compile release binaries across supported targets.
   cross-compile:
-    name: cross compilation (${{ matrix.sys }})
+    name: Release Cross-Compile (${{ matrix.sys }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -197,14 +191,12 @@ jobs:
         with:
           go-version: '${{ env.GO_VERSION }}'
 
-      - name: build release for ${{ matrix.sys }}
+      - name: Build release for ${{ matrix.sys }}
         run: make release sys=${{ matrix.sys }}
 
-  ########################
-  # Lint check.
-  ########################
+  # Run the lint suite for static analysis coverage.
   lint-check:
-    name: Lint check
+    name: Lint Suite
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -220,11 +212,9 @@ jobs:
       - name: run lint
         run: make lint
 
-  ########################
-  # Format check.
-  ########################
+  # Enforce formatting consistency.
   format-check:
-    name: Format check
+    name: Formatting Check
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -238,11 +228,9 @@ jobs:
       - name: run format
         run: make fmt
 
-  ########################
-  # check PR updates release notes
-  ########################
+  # Ensure pull requests update release notes unless explicitly skipped.
   milestone-check:
-    name: Check release notes updated
+    name: Release Notes Gate
     runs-on: ubuntu-latest
     if: '!contains(github.event.pull_request.labels.*.name, ''no-changelog'')'
     steps:
@@ -252,11 +240,9 @@ jobs:
       - name: Release notes check
         run: scripts/check-release-notes.sh
 
-  ########################
-  # run unit tests
-  ########################
+  # Unit tests with race detection, coverage, and Postgres backend variants.
   unit-test:
-    name: run unit tests
+    name: Unit Tests - ${{ matrix.unit_type }}
     runs-on: ubuntu-latest
     strategy:
       # Allow other tests in the matrix to continue if one fails.
@@ -275,7 +261,7 @@ jobs:
         with:
           go-version: '${{ env.GO_VERSION }}'
 
-      - name: run ${{ matrix.unit_type }}
+      - name: Run ${{ matrix.unit_type }}
         run: make ${{ matrix.unit_type }}
 
       - name: Send coverage
@@ -288,11 +274,9 @@ jobs:
           format: 'golang'
           parallel: true
 
-  ########################
-  # run integration tests
-  ########################
+  # Integration tests on SQLite backend.
   integration-test:
-    name: run itests
+    name: Integration Tests (SQLite)
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -331,11 +315,9 @@ jobs:
           format: 'golang'
           parallel: true
 
-  ########################
-  # run integration tests with Postgres backend
-  ########################
+  # Integration tests on Postgres backend.
   integration-test-postgres:
-    name: run itests postgres
+    name: Integration Tests (Postgres)
     runs-on: ubuntu-latest
     steps:
       - name: git checkout
@@ -374,18 +356,16 @@ jobs:
           format: 'golang'
           parallel: true
 
-  ########################
-  # Run LiTd tests
-  ########################
+  # LiT integration/unit tests with Taproot Assets replacements.
   run-lit:
-    name: run LiT ${{ matrix.task_name }}
+    name: LiT Tests - ${{ matrix.task_name }}
     runs-on: ubuntu-latest
     continue-on-error: true
     strategy:
       fail-fast: false
       matrix:
         include:
-          - task_name: itests custom_channels
+          - task_name: itests (custom_channels)
             run_cmd: make itest icase=custom_channels
           - task_name: unit
             run_cmd: make unit
@@ -401,8 +381,9 @@ jobs:
         working-directory: ./lightning-terminal
         run: ${{ matrix.run_cmd }}
 
-  # Notify about the completion of all coverage collecting jobs.
+  # Finalize Coveralls reporting after parallel coverage jobs.
   finish:
+    name: Finalize Coverage Reporting
     if: ${{ always() }}
     needs: [ unit-test ]
     runs-on: ubuntu-latest