CI: Add detailed descriptions in the workflow files and update maintainer guides

.github/workflows/cache_data.yaml

@@ -1,4 +1,13 @@
-# This workflow gets and uploads the GMT data artifacts used in the PyGMT CI tests
+# Cache GMT remote data files and uplodas as artifacts
+#
+# This workflow downloads data files needed by PyGMT tests/documentation from
+# the GMT data server and uploads as workflow artifacts which can be accessed
+# by other GitHub Actions workflows.
+#
+# It is scheduled to run every Sunday at 12:00 (UTC). If new remote files are
+# needed urgently, maintainers can manually uncomment the 'pull_request:' line
+# below to refresh the cache.
+#
 name: Cache data
 
 on:

.github/workflows/check-links.yml

@@ -1,4 +1,10 @@
-# This workflow checks the links in plaintext and HTML files
+# Check links in the repository and documentation
+#
+# This workflow runs the lychee tool to check all external links in plaintext
+# and HTML files. It will create an issue if broken links are found.
+#
+# It is scheduled to run weekly on 12 noon every Sunday.
+#
 name: Check Links
 
 on:

.github/workflows/ci_docs.yml

@@ -1,5 +1,18 @@
-# This workflow installs PyGMT, builds and deploys documentation
-
+# Build and deploy documentation
+#
+# This workflow builds the documentation on Linux/macOS/Windows.
+#
+# It is run on every commit to the main and pull request branches, and also
+# when a new release is published.
+# In draft pull requests, only the job on Linux is triggered to save on
+# Continuous Integration resources.
+#
+# On the main branch, the workflow also handles the documentation deployment:
+#
+# * Updating the development documentation by pushing the built HTML pages
+#   from the main branch onto the dev folder of the gh-pages branch.
+# * Updating the latest documentation link to the new release.
+#
 name: Docs
 
 on:

.github/workflows/ci_doctests.yaml

@@ -1,5 +1,8 @@
-# This workflow installs PyGMT and runs all doctests
-
+# Run all doctests on Linux/macOS/Windows
+#
+# This workflow runs all PyGMT doctests. It is scheduled to run weekly every
+# Sunday.
+#
 name: Doctests
 
 on:

.github/workflows/ci_tests.yaml

@@ -1,5 +1,25 @@
-# This workflow installs PyGMT and runs tests
-
+# Tests PyGMT on Linux/macOS/Windows
+#
+# This workflow runs regular PyGMT tests and uploads test coverage reports stored
+# in `.coverage.xml` to https://app.codecov.io/gh/GenericMappingTools/pygmt
+# via the [Codecov GitHub Action](https://github.com/codecov/codecov-action).
+# More codecov related configurations are stored in `.github/codecov.yml`.
+# If any tests fail, it also uploads the diff images as workflow artifacts.
+#
+# It is run:
+# 1. on every commit to the main branch
+# 2. on every commit to the pull request branches, unless the pull requests only
+#    contain non-code changes.
+# 3. when a new release is published
+#
+# It is also scheduled to run daily on the main branch.
+#
+# In draft pull request, only two jobs on Linux are triggered to save on
+# Continuous Integration resources:
+#
+# - Minimum [NEP29](https://numpy.org/neps/nep-0029-deprecation_policy) Python/NumPy versions
+# - Latest Python/NumPy versions + optional packages (e.g. GeoPandas)
+#
 name: Tests
 
 on:

.github/workflows/ci_tests_dev.yaml

@@ -1,5 +1,16 @@
-# This workflow installs PyGMT and runs tests on GMT dev version
-
+# Tests PyGMT with GMT dev version on Linux/macOS/Windows
+#
+# This workflow runs regular PyGMT tests with the GMT dev version.
+# If any tests fail, it also uploads the diff images as workflow artifacts.
+# On Linux/macOS, GMT dev version is installed by fetching the latest source
+# codes from the GMT master branch and compiling.
+# On Windows, GMT dev version is installed from the conda-forge's dev channel
+# due to the complexity of building GMT source codes on Windows.
+#
+# It is triggered when a pull request is marked as "ready as review", or using
+# the slash command `/test-gmt-dev`. It is also scheduled to run on Monday,
+# Wednesday, and Friday on the main branch.
+#
 name: GMT Dev Tests
 
 on:

.github/workflows/ci_tests_legacy.yaml

@@ -1,5 +1,11 @@
-# This workflow installs PyGMT and runs tests with old GMT versions
-
+# Tests PyGMT with GMT legacy versions on Linux/macOS/Windows
+#
+# This workflow runs regular PyGMT tests with GMT legacy versions. Due to the
+# minor baseline image changes between GMT versions, the workflow only runs
+# the tests but doesn't do image comparisons.
+#
+# It is scheduled to run every Tuesday on the main branch.
+#
 name: GMT Legacy Tests
 
 on:

.github/workflows/dvc-diff.yml

@@ -1,4 +1,12 @@
-# Checks for image diffs in a Pull Request and adds a GitHub comment showing the diff
+# Report changes in test images
+#
+# This workflow checks for image diffs in a pull request and adds a GitHub
+# comment showing the diff.
+#
+# It is triggered in a PR when any *.png.dvc files have been added, modified,
+# or deleted. A GitHub comment will be published that contains a summary table
+# of the images that have changed along with a visual report.
+#
 name: DVC image diff
 
 on:

.github/workflows/format-command.yml

@@ -1,3 +1,7 @@
+# Format the codes using slash command
+#
+# This workflow is triggered in a PR if the slash command `/format` is used.
+#
 name: format-command
 on:
   repository_dispatch:

.github/workflows/publish-to-pypi.yml

@@ -1,7 +1,17 @@
 # Publish archives to PyPI and TestPyPI using GitHub Actions
+#
+# This workflow is ran to publish PyGMT archives (source and binary distributions)
+# to TestPyPI (for testing only) and PyPI.
+#
+# Archives will be pushed to TestPyPI on every commit to the main branch and
+# tagged releases, and to PyPI for tagged releases only.
+#
+# Note that authentication to TestPyPI/PyPI is done via OpenID Connect, see also
+# https://github.com/pypa/gh-action-pypi-publish/tree/release/v1#publishing-with-openid-connect
+#
 # Important: this workflow filename must be publish-to-pypi.yml to match the
-# settings in PyPI and TestPyPI so that OIDC publishing works
-
+# settings in PyPI and TestPyPI so that OIDC publishing works.
+#
 name: Publish to PyPI
 
 # Only run for pushes to the main branch and releases.

.github/workflows/release-baseline-images.yml

@@ -1,5 +1,8 @@
 # Upload the ZIP archive of baseline images as a release asset
-
+#
+# This workflow is run to upload the ZIP archive of baseline images as a
+# release asset when a release is published.
+#
 name: Upload baseline images
 
 # Only run for releases

.github/workflows/release-drafter.yml

@@ -1,3 +1,9 @@
+# Draft the next release notes
+#
+# This workflow is run to update the next releases notes as pull requests are
+# merged into the main branch. The configuration file is located at
+# `.github/release-drafter.yml`.
+#
 name: Release Drafter
 
 on:

.github/workflows/slash-command-dispatch.yml

@@ -1,3 +1,7 @@
+# Support slash commands in pull requests
+#
+# Currently, two slash commands `format` and `test-gmt-dev` are supported.
+#
 name: Slash Command Dispatch
 on:
   issue_comment:

.github/workflows/style_checks.yaml

@@ -1,3 +1,11 @@
+# Code lint and style checks
+#
+# This workflow runs code style and lint checks to check if the codes have
+# consistent code style and are high-quality.
+#
+# It is run on every commit to the main and pull request branches. It is also
+# scheduled to run daily on the main branch.
+#
 name: Style Checks
 
 on:

doc/maintenance.md

@@ -64,96 +64,26 @@ The main advantages of this are:
 
 ## Continuous Integration
 
-We use GitHub Actions continuous integration (CI) services to
-build and test the project on Linux, macOS and Windows.
-They rely on the `environment.yml` file to install required dependencies using
-conda and the `Makefile` to run the tests and checks.
-
-There are 11 configuration files located in `.github/workflows`:
-
-1. `style_checks.yaml` (Code lint and style checks)
-
-   This is run on every commit to the *main* and pull request branches.
-   It is also scheduled to run daily on the *main* branch.
-
-2. `ci_tests.yaml` (Tests on Linux/macOS/Windows)
-
-   This is run on every commit to the *main* and pull request branches.
-   It is also scheduled to run regular tests daily on the *main* branch.
-   In draft pull requests, only two jobs on Linux are triggered to save on
-   Continuous Integration resources:
-
-   - Minimum [NEP29](https://numpy.org/neps/nep-0029-deprecation_policy)
-     Python/NumPy versions
-   - Latest Python/NumPy versions + optional packages (e.g. GeoPandas)
-
-   This workflow is also responsible for uploading test coverage reports stored
-   in `.coverage.xml` to https://app.codecov.io/gh/GenericMappingTools/pygmt
-   via the [Codecov GitHub Action](https://github.com/codecov/codecov-action).
-   More codecov related configurations are stored in `.github/codecov.yml`.
-
-3. `ci_doctests.yaml` (Doctests on Linux/macOS/Windows)
-
-    This workflow is scheduled to run all doctests every Sunday on the *main*
-    branch.
-
-4. `ci_docs.yml` (Build documentation on Linux/macOS/Windows)
-
-   This is run on every commit to the *main* and pull request branches.
-   In draft pull requests, only the job on Linux is triggered to save on
-   Continuous Integration resources.
-
-   On the *main* branch, the workflow also handles the documentation
-   deployment:
-
-   * Updating the development documentation by pushing the built HTML pages
-     from the *main* branch onto the `dev` folder of the *gh-pages* branch.
-   * Updating the `latest` documentation link to the new release.
-
-5. `ci_tests_dev.yaml` (GMT Dev Tests on Linux/macOS/Windows).
-
-   This is triggered when a PR is marked as "ready for review", or using the
-   slash command `/test-gmt-dev`. It is also scheduled to run on Monday,
-   Wednesday and Friday on the *main* branch.
-
-6. `cache_data.yaml` (Caches GMT remote data files needed for GitHub Actions CI)
-
-   This is scheduled to run every Sunday at 12:00 (UTC).
-   If new remote files are needed urgently, maintainers can manually uncomment
-   the 'pull_request:' line in that `cache_data.yaml` file to refresh the cache.
-
-7. `publish-to-pypi.yml` (Publish wheels to TestPyPI and PyPI)
-
-   This workflow is ran to publish wheels to TestPyPI (for testing only) and
-   PyPI. Archives will be pushed to TestPyPI on every commit to the *main*
-   branch and tagged releases, and to PyPI for tagged releases only. Note that
-   authentication to TestPyPI/PyPI is done via OpenID Connect, see also
-   https://github.com/pypa/gh-action-pypi-publish/tree/release/v1#publishing-with-openid-connect
-
-8. `release-drafter.yml` (Drafts the next release notes)
-
-    This workflow is run to update the next releases notes as pull requests are
-    merged into the *main* branch.
-
-9. `check-links.yml` (Check links in the repository and website)
-
-   This workflow is run weekly to check all external links in plaintext and
-   HTML files. It will create an issue if broken links are found.
-
-10. `format-command.yml` (Format the codes using slash command)
-
-   This workflow is triggered in a PR if the slash command `/format` is used.
-
-11. `dvc-diff.yml` (Report changes to test images on dvc remote)
-
-    This workflow is triggered in a PR when any *.png.dvc files have been added,
-    modified, or deleted. A GitHub comment will be published that contains a summary
-    table of the images that have changed along with a visual report.
-
-12. `release-baseline-images.yml` (Upload the ZIP archive of baseline images as a release asset)
-
-    This workflow is run to upload the ZIP archive of baseline images as a release
-    asset when a release is published.
+We use GitHub Actions continuous integration (CI) services to build, test and
+manage the project on Linux, macOS and Windows. The GitHub Actions CI are
+controlled by 14 workflow files located in `.github/workflows`. Here we briefly
+summarize the functions of the workflows. Please refer to the comments in the
+workflow files for more details.
+
+1. `style_checks.yaml`: Code lint and style checks
+2. `check-links.yml`: Check links in the repository and documentation
+3. `ci_tests.yaml`: Run regular PyGMT tests on Linux/macOS/Windows
+4. `ci_tests_dev.yaml`: Run regular PyGMT tests with GMT dev version on Linux/macOS/Windows
+5. `ci_tests_legacy.yaml`: Run regular PyGMT tests with GMT legacy versions on Linux/macOS/Windows
+6. `ci_docs.yml`: Build documentation on Linux/macOS/Windows and deploy to GitHub
+7. `ci_doctest.yaml`: Run all doctests on Linux/macOS/Windows
+8. `cache_data.yaml`: Cache GMT remote data files and uplodas as artifacts
+9. `publish-to-pypi.yml`: Publish archives to PyPI and TestPyPI
+10. `release-drafter.yml`: Draft the next release notes
+11. `release-baseline-images.yml`: Upload the ZIP archive of baseline images as a release asset
+12. `format-command.yml`: Format the codes using slash command
+13. `dvc-diff.yml`: Report changes in test images
+14. `slash-command-dispatch.yml`: Support slash commands in pull requests
 
 ## Continuous Documentation