From ee1f1a43b9c0d6b2a96709488aa83c4be9a58ab1 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Thu, 23 Nov 2023 23:49:06 +0000 Subject: [PATCH 1/2] docs(workflow): adds a description at the top of each file --- .github/workflows/cd-deploy-nodes-gcp.yml | 11 +++++++++++ .github/workflows/chore-project-management.yml | 8 +++++++- .github/workflows/ci-build-crates.yml | 10 ++++++++++ .github/workflows/ci-coverage.yml | 8 ++++++++ .github/workflows/ci-integration-tests-gcp.yml | 4 ++++ .github/workflows/ci-lint.yml | 7 +++++++ .github/workflows/ci-unit-tests-docker.yml | 11 +++++++++++ .github/workflows/ci-unit-tests-os.yml | 6 ++++++ .github/workflows/docs-deploy-firebase.yml | 4 ++++ .github/workflows/manual-zcashd-deploy.yml | 7 +++++++ .github/workflows/release-drafter.yml | 6 +++++- .github/workflows/sub-build-docker-image.yml | 6 ++++++ .github/workflows/sub-find-cached-disks.yml | 7 +++++++ .github/workflows/sub-test-zebra-config.yml | 4 ++++ 14 files changed, 97 insertions(+), 2 deletions(-) diff --git a/.github/workflows/cd-deploy-nodes-gcp.yml b/.github/workflows/cd-deploy-nodes-gcp.yml index bf6b9cb5842..97f74df79f5 100644 --- a/.github/workflows/cd-deploy-nodes-gcp.yml +++ b/.github/workflows/cd-deploy-nodes-gcp.yml @@ -1,3 +1,14 @@ +# This workflow automates the process of deploying Zebra nodes to Google Cloud Platform (GCP). Here's a breakdown of its jobs: +# +# 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 77ea4b44e2c..e3a5e3f8c5f 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 default 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 1132762c210..5e9ac9bf91d 100644 --- a/.github/workflows/ci-integration-tests-gcp.yml +++ b/.github/workflows/ci-integration-tests-gcp.yml @@ -1,3 +1,7 @@ +# This workflow performs a series of integration tests on GCP, primarily focusing on Zebra, but it also tests with Lightwalletd +# +# 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 1a0d44362e5..c61989e845b 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 5f90fbf2184..d57a5b4098d 100644 --- a/.github/workflows/ci-unit-tests-docker.yml +++ b/.github/workflows/ci-unit-tests-docker.yml @@ -1,3 +1,14 @@ +# Docker Unit Tests Workflow +# 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 c433bf82163..862a69590e9 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 29b85def5db..2f64fe1cca4 100644 --- a/.github/workflows/docs-deploy-firebase.yml +++ b/.github/workflows/docs-deploy-firebase.yml @@ -1,3 +1,7 @@ +# This workflow focuses on building and deploying different types of documentation for the Zebra project. +# - 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 11ace8f39e1..0f9ecb98387 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 1b929324619..8430abea675 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 12f39c398b4..1daac9257ea 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: From 7a41dc0c6b9ddb6420489fb83ebe33325b516bd7 Mon Sep 17 00:00:00 2001 From: Gustavo Valverde Date: Mon, 4 Dec 2023 22:42:33 +0000 Subject: [PATCH 2/2] Update .github/workflows/ci-build-crates.yml Co-authored-by: Marek --- .github/workflows/ci-build-crates.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci-build-crates.yml b/.github/workflows/ci-build-crates.yml index e3a5e3f8c5f..4067a19efac 100644 --- a/.github/workflows/ci-build-crates.yml +++ b/.github/workflows/ci-build-crates.yml @@ -2,7 +2,7 @@ # 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 default features. +# - 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