maintainers/haskell/update*: print version diff when not committing

This allows other scripts to detect whether anything changed without
resorting to git-diff(1): If nothing changed, stdout will be empty (i.e.
we now enforce that other messages go to stderr). To make sure that this
behavior is retained in the future, the scripts' behavior is briefly
documented in the files' header.

maintainers/scripts/haskell/update-hackage.sh

@@ -1,7 +1,26 @@
 #! /usr/bin/env nix-shell
 #! nix-shell -i bash -p curl jq git gnused -I nixpkgs=.
-
+#
-# See regenerate-hackage-packages.sh for details on the purpose of this script.
+# SYNOPSIS
+#
+#   Update Hackage index and hashes data exposed via pkgs.all-cabal-hashes.
+#
+# DESCRIPTION
+#
+#   Find latest revision of the commercialhaskell/all-cabal-hashes repository's
+#   hackage branch and update pkgs/data/misc/hackage/pin.json accordingly.
+#
+#   This data is used by hackage2nix to generate hackage-packages.nix. Since
+#   hackage2nix uses the latest version of a package unless an explicit
+#   constraint is configured, running this script indirectly updates packages
+#   (when hackage2nix is executed afterwards).
+#
+#   Prints a version difference to stdout if the pin has been updated, nothing
+#   otherwise.
+#
+# EXIT STATUS
+#
+#   Always exit with zero (even if nothing changed) unless there was an error.
 
 set -euo pipefail
 
@@ -14,6 +33,7 @@ commit_msg="$(echo "$git_info" | jq -r .commit.commit.message)"
 new_date="$(echo "$commit_msg" | sed 's/Update from Hackage at //')"
 
 if [ "$current_commit" != "$head_commit" ]; then
+   echo "Updating all-cabal-hashes from $old_date to $new_date" >&2
    url="https://github.com/commercialhaskell/all-cabal-hashes/archive/$head_commit.tar.gz"
    hash="$(nix-prefetch-url "$url")"
    jq -n \
@@ -23,13 +43,19 @@ if [ "$current_commit" != "$head_commit" ]; then
      --arg commit_msg "$commit_msg" \
      '{commit: $commit, url: $url, sha256: $hash, msg: $commit_msg}' \
      > $pin_file
+else
+   echo "No new all-cabal-hashes version" >&2
 fi
 
+version_diff="$old_date -> $new_date"
+
 if [[ "${1:-}" == "--do-commit" ]]; then
 git add pkgs/data/misc/hackage/pin.json
 git commit -F - << EOF
-all-cabal-hashes: $old_date -> $new_date
+all-cabal-hashes: $version_diff
 
 This commit has been generated by maintainers/scripts/haskell/update-hackage.sh
 EOF
+else
+echo "$version_diff"
 fi

maintainers/scripts/haskell/update-stackage.sh

@@ -1,6 +1,28 @@
 #! /usr/bin/env nix-shell
 #! nix-shell -i bash -p curl jq git gnused gnugrep -I nixpkgs=.
 # shellcheck shell=bash
+#
+# SYNOPSIS
+#
+#   Update version constraints in hackage2nix config file from Stackage.
+#
+# DESCRIPTION
+#
+#   Fetches the latest snapshot of the configured Stackage solver which is
+#   configured via the SOLVER (either LTS or Nightly) and VERSION variables in
+#   the script.
+#
+#   VERSION is only applicable if SOLVER is LTS. SOLVER=LTS and VERSION=22
+#   will cause update-stackage.sh to fetch the latest LTS-22.XX version.
+#   If empty, the latest version of the solver is used.
+#
+#   If the configuration file has been updated, update-stackage.sh prints a
+#   version difference to stdout, e.g. 23.11 -> 23.13. Otherwise, stdout remains
+#   empty.
+#
+# EXIT STATUS
+#
+#   Always exit with zero (even if nothing changed) unless there was an error.
 
 set -eu -o pipefail
 
@@ -31,11 +53,11 @@ old_version=$(grep '^# Stackage' $stackage_config | sed -e 's/.\+ \([A-Za-z]\+ [
 version="$SOLVER $(sed -rn "s/^--.*http:..(www.)?stackage.org.snapshot.$(toLower "$SOLVER")-//p" "$tmpfile")"
 
 if [[ "$old_version" == "$version" ]]; then
-   echo "No new stackage version"
+   echo "No new stackage version" >&2
    exit 0 # Nothing to do
 fi
 
-echo "Updating Stackage from $old_version to $version."
+echo "Updating Stackage from $old_version to $version." >&2
 
 # Create a simple yaml version of the file.
 sed -r \
@@ -78,11 +100,15 @@ sed -r \
 # ShellCheck: latest version of command-line dev tool.
 # Agda: The Agda community is fast-moving; we strive to always include the newest versions of Agda and the Agda packages in nixpkgs.
 
+version_diff="$old_version -> $version"
+
 if [[ "${1:-}" == "--do-commit" ]]; then
 git add $stackage_config
 git commit -F - << EOF
-haskellPackages: stackage $old_version -> $version
+haskellPackages: stackage $version_diff
 
 This commit has been generated by maintainers/scripts/haskell/update-stackage.sh
 EOF
+else
+echo "$version_diff"
 fi