chore(ci): document gha workflows

Signed-off-by: Sam Gammon <[email protected]>

.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:

.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:

.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:

.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:

.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: