A few changes for clarity

ci-tools/update-nixpkgs

@@ -116,9 +116,15 @@ checkout_source_branch() {
     # tends to like to share across builds) clone it to a new temporary path.
     git clone . working-copy
     cd working-copy
+
+    # Make sure we know the name of a remote that points at the right place.
+    # Then use it to make sure the base branch is up-to-date.  It usually
+    # should be already but in case it isn't we don't want to start from a
+    # stale revision.
     git remote add upstream gitlab@"$SERVER_HOST":"$PROJECT_PATH".git
     refresh_ssh_key "$SSHKEY"
     git fetch upstream "$DEFAULT_BRANCH"
+
     # Typically this tool runs infrequently enough that the branch doesn't
     # already exist.  However, as a convenience for developing on this tool
     # itself, if it does already exist, wipe it and start fresh for greater
@@ -129,8 +135,8 @@ checkout_source_branch() {
     git checkout -B "${BRANCH}" upstream/"$DEFAULT_BRANCH"
 }
 
-# Do the "before nixpkgs change" build to use as the base of the diff we
-# compute later.
+# Build all of the grids (the `morph` attribute of `default.nix`) and link the
+# result to the given parameter.  This will give us some material to diff.
 build() {
     # The name of the nix result symlink.
     local RESULT=$1
@@ -197,9 +203,11 @@ create_merge_request() {
     shift
     local PROJECT_ID=$1
     shift
-    local DEFAULT_BRANCH=$1
+    # The target branch of the MR.
+    local TARGET_BRANCH=$1
     shift
-    local BRANCH=$1
+    # THe source branch of the MR.
+    local SOURCE_BRANCH=$1
     shift
     local DIFF=$1
     shift
@@ -207,7 +215,12 @@ create_merge_request() {
     local BODY=$(python3 -c '
 import sys, json, re
 def rewrite_escapes(s):
+    # `nix store diff-closures` output is fancy and includes color codes and
+    # such.  That looks a bit less than nice in a markdown-formatted comment so
+    # strip all of it.  If we wanted to be fancy we could rewrite it in a
+    # markdown friendly way (eg using html).
     return re.sub(r"\x1b\[[^m]*m", "", s)
+
 print(json.dumps({
     "id": sys.argv[1],
     "target_branch": sys.argv[2],
@@ -216,7 +229,7 @@ print(json.dumps({
     "title": "bump nixpkgs version",
     "description": f"```\n{rewrite_escapes(sys.argv[4])}\n```",
 }))
-' "$PROJECT_ID" "$DEFAULT_BRANCH" "$BRANCH" "$DIFF")
+' "$PROJECT_ID" "$TARGET_BRANCH" "$SOURCE_BRANCH" "$DIFF")
 
     curl --verbose -X POST --data "${BODY}" --header "Content-Type: application/json" --header "PRIVATE-TOKEN: ${TOKEN}" "${SERVER_URL}/api/v4/projects/${PROJECT_ID}/merge_requests"
 }