diff --git a/.github/workflows/cd-deploy-nodes-gcp.yml b/.github/workflows/cd-deploy-nodes-gcp.yml index 9515a4244f1..e77302a7340 100644 --- a/.github/workflows/cd-deploy-nodes-gcp.yml +++ b/.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 diff --git a/.github/workflows/chore-project-management.yml b/.github/workflows/chore-project-management.yml index b9c4e1a8bd8..4825e353c94 100644 --- a/.github/workflows/chore-project-management.yml +++ b/.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: diff --git a/.github/workflows/ci-build-crates.yml b/.github/workflows/ci-build-crates.yml index 823ac95f0f2..1eecbbbfe01 100644 --- a/.github/workflows/ci-build-crates.yml +++ b/.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 diff --git a/.github/workflows/ci-coverage.yml b/.github/workflows/ci-coverage.yml index 5d6179fed92..482b0d7db84 100644 --- a/.github/workflows/ci-coverage.yml +++ b/.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 diff --git a/.github/workflows/ci-integration-tests-gcp.yml b/.github/workflows/ci-integration-tests-gcp.yml index 902575c56a5..e0d2e07e655 100644 --- a/.github/workflows/ci-integration-tests-gcp.yml +++ b/.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 diff --git a/.github/workflows/ci-lint.yml b/.github/workflows/ci-lint.yml index 50296e738c1..d72a53395be 100644 --- a/.github/workflows/ci-lint.yml +++ b/.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 diff --git a/.github/workflows/ci-unit-tests-docker.yml b/.github/workflows/ci-unit-tests-docker.yml index a0a1e7c115e..4785544413e 100644 --- a/.github/workflows/ci-unit-tests-docker.yml +++ b/.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 diff --git a/.github/workflows/ci-unit-tests-os.yml b/.github/workflows/ci-unit-tests-os.yml index 4075cbd20fb..b02c36adf3d 100644 --- a/.github/workflows/ci-unit-tests-os.yml +++ b/.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 diff --git a/.github/workflows/docs-deploy-firebase.yml b/.github/workflows/docs-deploy-firebase.yml index a1095f59fd4..21930a1b93b 100644 --- a/.github/workflows/docs-deploy-firebase.yml +++ b/.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 diff --git a/.github/workflows/manual-zcashd-deploy.yml b/.github/workflows/manual-zcashd-deploy.yml index 7bfb5cf70eb..158f919c99f 100644 --- a/.github/workflows/manual-zcashd-deploy.yml +++ b/.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: diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml index 39e1ba7bde2..c2d2d811982 100644 --- a/.github/workflows/release-drafter.yml +++ b/.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 diff --git a/.github/workflows/sub-build-docker-image.yml b/.github/workflows/sub-build-docker-image.yml index 19912f40b3d..1ac07708a1a 100644 --- a/.github/workflows/sub-build-docker-image.yml +++ b/.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: diff --git a/.github/workflows/sub-find-cached-disks.yml b/.github/workflows/sub-find-cached-disks.yml index 49d6083ec8f..5ca79720131 100644 --- a/.github/workflows/sub-find-cached-disks.yml +++ b/.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: diff --git a/.github/workflows/sub-test-zebra-config.yml b/.github/workflows/sub-test-zebra-config.yml index 6ed561cbd7e..19391cc4b0b 100644 --- a/.github/workflows/sub-test-zebra-config.yml +++ b/.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: