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