From 07e84fde42c1e2b57086c2ed137477edbb99000b Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 5 Jan 2022 09:01:59 -1000
Subject: [PATCH] ci: doc improvements

---
 .github/workflows/linux-arm32v7.yml |  6 ++++++
 .github/workflows/linux-x64.yml     |  5 +++++
 .github/workflows/mac.yml           |  2 +-
 .github/workflows/pull.yml          | 15 ++++-----------
 .github/workflows/push.yml          |  9 ++++-----
 .github/workflows/windows.yml       |  2 +-
 tools/release                       |  6 ++++++
 7 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/linux-arm32v7.yml b/.github/workflows/linux-arm32v7.yml
index 47104931c..96ad0ab00 100644
--- a/.github/workflows/linux-arm32v7.yml
+++ b/.github/workflows/linux-arm32v7.yml
@@ -1,3 +1,9 @@
+# Runs on any push to ci-linux-arm32v7.
+# Produces optimised static arm32v7 linux  binaries,
+# using GHC 8.10.4 and cabal.
+# Currently runs no tests.
+# Slow, will probably time out.
+
 name: linux-arm32v7 CI binaries
 
 on:
diff --git a/.github/workflows/linux-x64.yml b/.github/workflows/linux-x64.yml
index 66838e807..db556438e 100644
--- a/.github/workflows/linux-x64.yml
+++ b/.github/workflows/linux-x64.yml
@@ -1,3 +1,8 @@
+# Runs on any push to ci-linux-x64.
+# Produces optimised static x64 linux  binaries,
+# using the GHC version below (9.0.1) and cabal.
+# Currently runs no tests.
+
 name: linux-x64 CI binaries
 
 on:
diff --git a/.github/workflows/mac.yml b/.github/workflows/mac.yml
index a9595c92b..258c8d9b2 100644
--- a/.github/workflows/mac.yml
+++ b/.github/workflows/mac.yml
@@ -1,6 +1,6 @@
 # Runs on any push to ci-mac, and weekly on master.
 # Produces optimised mac binaries and runs unit/doc/functional tests,
-# using the GHC version below.
+# using the default stack.yaml's GHC version.
 
 name: mac CI binaries
 
diff --git a/.github/workflows/pull.yml b/.github/workflows/pull.yml
index c60dc7875..9b6342489 100644
--- a/.github/workflows/pull.yml
+++ b/.github/workflows/pull.yml
@@ -1,15 +1,8 @@
-# Runs on notable pull requests against master,
-# and also weekly on master.
+# Runs on notable pull requests against master, and weekly on master.
+# Runs unit/doc/functional/haddock/bench tests and produces optimised dynamic x64 linux binaries,
+# using the oldest supported GHC version (8.6).
 
-# Builds all modules optimised and runs
-# unit/doc/functional/haddock/benchmark tests on linux,
-# using the oldest supported GHC version (only, as a compromise to
-# reduce carbon emissions. Some of the other versions are exercised by
-# the other workflows.)
-# Currently does not upload a binaries artifact.
-
-# This is the "master" workflow on which the others are based, 
-# with the most detailed notes.
+# This was the original workflow, and may have the most detailed notes.
 
 name: pull request CI
 
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
index 68edc6273..fc136c8ff 100644
--- a/.github/workflows/push.yml
+++ b/.github/workflows/push.yml
@@ -1,8 +1,7 @@
-# Runs on (after) notable pushes to master.
-# Failure does not block the push.
-
-# Builds incrementally and runs functional tests on linux,
-# using the latest supported GHC version.
+# Runs on notable pushes to master.
+# Builds incrementally and unoptimised on x64 linux and runs functional tests,
+# using the GHC version below (8.10.7).
+# Build/test failure does not block the push.
 
 name: push CI
 
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
index c1f358180..2216d5d1d 100644
--- a/.github/workflows/windows.yml
+++ b/.github/workflows/windows.yml
@@ -1,6 +1,6 @@
 # Runs on any push to ci-windows, and weekly on master.
 # Produces optimised windows binaries,
-# using the default GHC version in stack.yaml.
+# using the default stack.yaml's GHC version.
 # Currently runs no tests.
 
 name: windows CI binaries
diff --git a/tools/release b/tools/release
index b249e52f2..7ff10044f 100755
--- a/tools/release
+++ b/tools/release
@@ -124,3 +124,9 @@ bin() {
 }
 
 if declare -f "$1" > /dev/null; then "$@"; else usage; fi
+
+# ** notes
+# *** rerunning 
+# **** creates empty doc update commits
+# **** creates duplicate changelog headings
+# ***** CHANGES.md's version "1.24.99.1" is not yet tagged, can't list changes