From db009548454929b65d1c40f1b3c3d191c10127fa Mon Sep 17 00:00:00 2001 From: Sam Gammon Date: Thu, 7 Mar 2024 23:17:57 -0800 Subject: [PATCH] chore(ci): document gha workflows Signed-off-by: Sam Gammon --- .github/workflows/ci.build.yml | 21 +++++++++++++++++++++ .github/workflows/ci.test.yml | 21 +++++++++++++++++++++ .github/workflows/dependency-review.yml | 13 +++++++++++++ .github/workflows/on.pr.yml | 8 ++++++++ .github/workflows/on.push.yml | 8 ++++++++ 5 files changed, 71 insertions(+) diff --git a/.github/workflows/ci.build.yml b/.github/workflows/ci.build.yml index 7a13f13c9caa..460bce180945 100644 --- a/.github/workflows/ci.build.yml +++ b/.github/workflows/ci.build.yml @@ -1,3 +1,24 @@ +# Guava GitHub CI +# --------------------------------------------------------------------------------------------------------------------- +# This is the main CI build on GitHub for the Google Guava project. This workflow is not invoked directly; instead, the +# `on.pr.yml` and `on.push.yml` workflows kick in on PR and push events, respectively, and call this workflow as a +# Reusable Workflow. +# +# This workflow can be tested independently of the entrypoint flow through the `workflow_dispatch` hook, which adds a +# button within the UI of the GitHub repository. You can trigger the workflow from here: +# +# https://github.com/google/guava/actions/workflows/ci.build.yml +# +# ## Inputs +# +# See the set of input parameters underneath the `workflow_call` and `workflow_dispatch` hooks for ways this workflow +# can be controlled when called. +# +# ## SLSA Provenance +# +# After building Guava in both JRE and Android variants, this workflow will (if enabled) generate provenance material +# and upload it to an associated release. Learn more about SLSA here: https://slsa.dev. + name: Build on: diff --git a/.github/workflows/ci.test.yml b/.github/workflows/ci.test.yml index cea38296fe43..b8625eff76e3 100644 --- a/.github/workflows/ci.test.yml +++ b/.github/workflows/ci.test.yml @@ -1,3 +1,24 @@ +# Guava GitHub CI +# --------------------------------------------------------------------------------------------------------------------- +# This is the main CI testsuite on GitHub for the Google Guava project. This workflow is not invoked directly; instead, +# the `on.pr.yml` and `on.push.yml` workflows kick in on PR and push events, respectively, and call this workflow as a +# Reusable Workflow. +# +# This workflow can be tested independently of the entrypoint flow through the `workflow_dispatch` hook, which adds a +# button within the UI of the GitHub repository. You can trigger the workflow from here: +# +# https://github.com/google/guava/actions/workflows/ci.test.yml +# +# ## Inputs +# +# See the set of input parameters underneath the `workflow_call` and `workflow_dispatch` hooks for ways this workflow +# can be controlled when called. +# +# ## Multi-OS and Multi-JVM Testing +# +# Guava is tested against each LTS release at JDK 8 through JDK 21, on Linux and on Windows (starting at JDK 17), and +# in Android and JRE flavors. + name: Tests on: diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index f302b07d983b..abc802dae2ac 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -1,3 +1,16 @@ +# Guava GitHub CI +# --------------------------------------------------------------------------------------------------------------------- +# This workflow is called from `on.push.yml` and `on.pr.yml` to operate on Guava's dependency graph: +# +# - The dependency graph is calculated from pom.xml files +# - The graph is then published to GitHub, and associated with the Guava repository +# - When operating on a PR, Dependency Review can be invoked to check dependency changes +# +# ## Inputs +# +# See the set of input parameters underneath the `workflow_call` and `workflow_dispatch` hooks for ways this workflow +# can be controlled when called. + name: 'Dependency Graph' on: workflow_call: diff --git a/.github/workflows/on.pr.yml b/.github/workflows/on.pr.yml index 404f308f2319..a7cd494d7e69 100644 --- a/.github/workflows/on.pr.yml +++ b/.github/workflows/on.pr.yml @@ -1,3 +1,11 @@ +# Guava GitHub CI +# --------------------------------------------------------------------------------------------------------------------- +# This is an entrypoint workflow which operates on pull requests; this workflow doesn't do much on its own. Its job is +# to dispatch `on.build.yml` and check workflows, which can be found in this same directory. +# +# PR workflows are slightly different from push workflows (for example, they do not publish snapshots). See the +# `on.push.yml` workflow. PR and push flows are designed to be invoked separately. + name: PR on: diff --git a/.github/workflows/on.push.yml b/.github/workflows/on.push.yml index 76a87d7a6551..d34a85f6c1e7 100644 --- a/.github/workflows/on.push.yml +++ b/.github/workflows/on.push.yml @@ -1,3 +1,11 @@ +# Guava GitHub CI +# --------------------------------------------------------------------------------------------------------------------- +# This is an entrypoint workflow which operates on pushed revisions to Guava; this workflow doesn't do much on its own. +# Its job is to dispatch `on.build.yml` and check workflows, which can be found in this same directory. +# +# PR workflows are slightly different from push workflows (for example, the push workflow publishes snapshots). See the +# `on.pr.yml` workflow. PR and push flows are designed to be invoked separately. + name: Push on: