add comments to unreleased.sh (#3575)

unreleased.sh

@@ -9,7 +9,35 @@ if [ "$#" -ne 1 ]; then
     exit 64
 fi
 
-for SHA in $(git log --format=%H "$1"); do
-  git show --quiet --format=%b "$SHA" \
-    | awk '/^$/{next} toupper($0) ~ /CHANGELOG_END/{flag=0; next} toupper($0) ~ /CHANGELOG_BEGIN/{flag=1; next} flag'
+set -euo pipefail
+
+COMMITS_IN_GIVEN_RANGE=$(git log --format=%H "$1")
+
+extract_changelog () {
+    awk '
+        # Skip empty lines.
+        /^$/ {next}
+
+        # Take entire line, uppercase, compare to CHANGELOG_END.
+        # If it matches, set flag to 0 (false) and skip current line.
+        toupper($0) ~ /CHANGELOG_END/ { flag=0; next }
+
+        # If uppercased line matches CHANGELOG_BEGIN, skip current line and set
+        # flag to 1 (true).
+        toupper($0) ~ /CHANGELOG_BEGIN/ { flag=1; next }
+
+        # Because all previous cases skip the current line, if we reach this
+        # point we know that the current line is not blank, does not contain
+        # CHANGELOG_END, and does not contain CHANGELOG_BEGIN. Here we match
+        # the line based on the value of flag, regardless of the content of the
+        # line. Because there is no action associated with this condition, the
+        # default one is applied when it matches (i.e. when flag != 0), which
+        # is to print the entire current line.
+        flag
+    '
+}
+
+for SHA in $COMMITS_IN_GIVEN_RANGE; do
+    COMMIT_MESSAGE_BODY=$(git show --quiet --format=%b "$SHA")
+    echo "$COMMIT_MESSAGE_BODY" | extract_changelog
 done