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