docs(workflow): adds a description at the top of each file

.github/workflows/cd-deploy-nodes-gcp.yml

@@ -1,6 +1,16 @@
 # Google Cloud node deployments and tests that run when Rust code or dependencies are modified,
 # but only on PRs from the ZcashFoundation/zebra repository.
-# (External PRs are tested/deployed by mergify.)
+# (External PRs are tested/deployed by mergify.) 
+#
+# 1. `versioning`: Extracts the major version from the release semver. Useful for segregating instances based on major versions.
+# 2. `build`: Builds a Docker image named `zebrad` with the necessary tags derived from Git.
+# 3. `test-configuration-file`: Validates Zebra using the default config with the latest version.
+# 4. `test-configuration-file-testnet`: Tests the Docker image for the testnet configuration.
+# 5. `test-zebra-conf-path`: Verifies Zebra with a custom Docker config file.
+# 6. `deploy-nodes`: Deploys Managed Instance Groups (MiGs) for Mainnet and Testnet. If triggered by main branch pushes, it always replaces the MiG. For releases, MiGs are replaced only if deploying the same major version; otherwise, a new major version is deployed.
+# 7. `deploy-instance`: Deploys a single node in a specified GCP zone for testing specific commits. Instances from this job aren't auto-replaced or deleted.
+#
+# The overall goal is to ensure that Zebra nodes are consistently deployed, tested, and managed on GCP.
 name: Deploy Nodes to GCP
 
 # Ensures that only one workflow task will run at a time. Previous deployments, if

.github/workflows/chore-project-management.yml

@@ -1,6 +1,12 @@
+# This workflow manages the automatic addition of new issues to specific GitHub projects.
+#
+# 1. Newly opened issues are added to the "Zebra Backlog" Github project.
+# 2. They are also added to the "ZF Engineering Backlog" Github project.
+#
+# The action makes use of the `add-to-project` action and requires a Github token
+# (currently sourced from secrets) to authenticate and perform the addition.
 name: Add new issues to GitHub projects
 
-# Configuration for automatically adding issues to various Github projects for Project Management purposes
 on:
   issues:
     types:

.github/workflows/ci-build-crates.yml

@@ -1,3 +1,13 @@
+# This workflow facilitates the individual building of Rust crates present in the repository.
+# 1. A matrix is generated dynamically to identify each crate in the repository.
+# 2. This matrix is checked for validity.
+# 3. Each identified crate undergoes three build processes:
+#    - With no features.
+#    - With the default features.
+#    - With all the features enabled.
+# 4. In case of build failures outside of pull requests, an issue is either opened or updated
+#    in the repository to report the failure.
+# Throughout the workflow, various setup steps ensure the correct environment and tools are present.
 name: Build crates individually
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/ci-coverage.yml

@@ -1,3 +1,11 @@
+# This workflow calculates the test coverage for the Rust codebase.
+# 1. The code is checked out.
+# 2. Rust with the stable toolchain, minimal profile, and llvm-tools-preview component is set up.
+# 3. Necessary tools like 'cargo-llvm-cov' are installed.
+# 4. Proptest is minimized for efficient coverage test runs.
+# 5. Tests are run without producing a report to gather coverage information.
+# 6. A coverage report (lcov format) is generated based on the gathered information.
+# 7. Finally, this report is uploaded to Codecov for visualization and analysis.
 name: Coverage
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/ci-integration-tests-gcp.yml

@@ -1,5 +1,8 @@
 # Google Cloud integration tests that run when Rust code or dependencies are modified,
 # but only on PRs from the ZcashFoundation/zebra repository. (External PRs are tested by mergify.)
+#
+# Specific conditions and dependencies are set for each job to ensure they are executed in the correct sequence and under the right circumstances.
+# Each test has a description of the conditions under which it runs.
 name: Integration Tests on GCP
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/ci-lint.yml

@@ -1,3 +1,10 @@
+# This workflow conducts various linting checks for a Rust-based project.
+# 1. Determines if Rust or workflow files have been modified.
+# 2. Runs the Clippy linter on Rust files, producing annotations and failing on warnings.
+# 3. Ensures Rust code formatting complies with 'rustfmt' standards.
+# 4. Lints GitHub Actions workflow files for common issues.
+# 5. Checks for common spelling errors in the codebase.
+# The workflow is designed to maintain code quality and consistency, running checks conditionally based on the changed files.
 name: Lint
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/ci-unit-tests-docker.yml

@@ -1,5 +1,16 @@
 # Google Cloud unit tests that run when Rust code or dependencies are modified,
 # but only on PRs from the ZcashFoundation/zebra repository. (External PRs are tested by mergify.)
+#
+# This workflow is designed for running various unit tests within Docker containers.
+# Jobs:
+# 1. Builds a Docker image for tests, adaptable to the specified network (Mainnet or Testnet).
+# 2. 'test-all': Executes all Zebra tests, including normally ignored ones, in a Docker environment.
+# 3. 'test-fake-activation-heights': Runs state tests with fake activation heights, isolating its build products.
+# 4. 'test-empty-sync': Tests Zebra's ability to sync and checkpoint from an empty state.
+# 5. 'test-lightwalletd-integration': Validates integration with 'lightwalletd' starting from an empty state.
+# 6. 'test-configuration-file': Assesses the default Docker configuration for Zebra.
+# 7. 'test-configuration-file-testnet': Checks the Docker image reconfiguration for the Testnet.
+# 8. 'test-zebra-conf-path': Tests Zebra using a custom Docker configuration.
 name: Docker Unit Tests
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/ci-unit-tests-os.yml

@@ -1,3 +1,9 @@
+# This workflow performs unit tests across different operating systems and Rust versions. It includes steps for:
+# - Testing on Ubuntu and macOS with stable and beta Rust toolchains.
+# - Installing Zebra from the lockfile without cache on Ubuntu.
+# - Verifying that Cargo.lock is up-to-date with Cargo.toml changes.
+# - Running cargo-deny checks for dependencies.
+# - Checking for unused dependencies in the code.
 name: Multi-OS Unit Tests
 
 # Ensures that only one workflow task will run at a time. Previous builds, if

.github/workflows/docs-deploy-firebase.yml

@@ -1,5 +1,9 @@
 # Google Cloud docs updates that run when docs, Rust code, or dependencies are modified,
 # but only on PRs from the ZcashFoundation/zebra repository. (External PRs are deployed by mergify.)
+
+# - Builds and deploys Zebra Book Docs using mdBook, setting up necessary tools and deploying to Firebase.
+# - Compiles and deploys external documentation, setting up Rust with the beta toolchain and default profile, building the docs, and deploying them to Firebase.
+# - Assembles and deploys internal documentation with similar steps, including private items in the documentation, and deploys to Firebase.
 name: Docs
 
 # Ensures that only one workflow task will run at a time. Previous deployments, if

.github/workflows/manual-zcashd-deploy.yml

@@ -1,3 +1,10 @@
+# This workflow is designed for manually deploying zcashd nodes to Google Cloud Platform (GCP) based on user inputs.
+# - Allows selection of network type (Mainnet or Testnet) and instance group size.
+# - Converts network name to lowercase to comply with GCP labeling requirements.
+# - Authenticates with Google Cloud using provided credentials.
+# - Creates a GCP instance template from a container image of zcashd.
+# - Checks if the specified instance group already exists.
+# - Depending on the existence check, either creates a new managed instance group or updates the existing one with the new template.
 name: Zcashd Manual Deploy
 
 on:

.github/workflows/release-drafter.yml

@@ -1,6 +1,10 @@
-# Creates a draft release with all the PR names since the last release.
+# This workflow automates the creation and updating of draft releases. It compiles PR titles into the draft release notes.
 # https://github.com/ZcashFoundation/zebra/releases
 #
+# - Updates the draft release upon each merge into 'main'.
+# - Utilizes the release-drafter GitHub Action to accumulate PR titles since the last release into a draft release note.
+# - Suitable permissions are set for creating releases and handling pull requests.
+#
 # Workflow is based on:
 # https://github.com/marketplace/actions/release-drafter#usage
 name: Release Drafter

.github/workflows/sub-build-docker-image.yml

@@ -1,3 +1,9 @@
+# This workflow automates the building and pushing of Docker images based on user-defined inputs. It includes:
+# - Accepting various inputs like image name, Dockerfile path, target, and additional Rust-related parameters.
+# - Authenticates with Google Cloud and logs into Google Artifact Registry and DockerHub.
+# - Uses Docker Buildx for improved build performance and caching.
+# - Builds the Docker image and pushes it to both Google Artifact Registry and potentially DockerHub, depending on release type.
+# - Manages caching strategies to optimize build times across different branches.
 name: Build docker image
 
 on:

.github/workflows/sub-find-cached-disks.yml

@@ -1,3 +1,10 @@
+# Check if Cached State Disks Exist Workflow
+# This workflow is designed to check the availability of cached state disks in Google Cloud Platform (GCP) for different types of Zcash applications.
+# - Accepts network type as input to determine which disks to search for.
+# - Checks for the existence of three types of disks: lightwalletd tip, Zebra tip, and Zebra checkpoint.
+# - Uses Google Cloud SDK to query and identify available disks based on network and version.
+# - Outputs the availability of each disk type, which can be utilized in subsequent workflows.
+# The workflow streamlines the process of verifying disk availability, crucial for optimizing and speeding up integration tests and deployments.
 name: Check if cached state disks exist
 
 on:

.github/workflows/sub-test-zebra-config.yml

@@ -1,3 +1,7 @@
+# This workflow is designed to test Zebra configuration files using Docker containers.
+# - Runs a specified Docker image with the provided test variables and network settings.
+# - Monitors and analyzes container logs for specific patterns to determine test success.
+# - Provides flexibility in testing various configurations and networks by dynamically adjusting input parameters.
 name: Test Zebra Config Files
 
 on: