more callback docs

diff --git a/src/ci/docker/x86_64-gnu-tools/repo.sh b/src/ci/docker/x86_64-gnu-tools/repo.sh
index 35ab7e2b8c839392114e6b5af1567ba2c0a5c352..f06129551a464158d0d2827e862375b9fcee1d4d 100644 (file)
--- a/src/ci/docker/x86_64-gnu-tools/repo.sh
+++ b/src/ci/docker/x86_64-gnu-tools/repo.sh
@@ -62,10 +62,13 @@ commit_toolstate_change() {
     MESSAGE_FILE="$1"
     shift
     for RETRY_COUNT in 1 2 3 4 5; do
-        # Call the callback; this will in the end call `change_toolstate` from
-        # `checktools.sh` if we are in the `auto` branch (pre-landing) or
-        # `src/tools/publish_toolstate.py` if we are in the `master` branch
-        # (post-landing).
+        # Call the callback.
+        # - If we are in the `auto` branch (pre-landing), this is called from `checktools.sh` and
+        #   the callback is `change_toolstate` in that file. The purpose of this is to publish the
+        #   test results (the new commit-to-toolstate mapping) in the toolstate repo.
+        # - If we are in the `master` branch (post-landing), this is called by the CI pipeline
+        #   and the callback is `src/tools/publish_toolstate.py`. The purpose is to publish
+        #   the new "current" toolstate in the toolstate repo.
         "$@"
         # `git commit` failing means nothing to commit.
         FAILURE=0

diff --git a/src/tools/publish_toolstate.py b/src/tools/publish_toolstate.py
index 8f9061d7c181111ce22ae11fe5f723fe975e4101..0f1ae5e0eb2edc58a6d4e1b4396d3eba4ea2a19f 100755 (executable)
--- a/src/tools/publish_toolstate.py
+++ b/src/tools/publish_toolstate.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+## This is set as callback for `src/ci/docker/x86_64-gnu-tools/repo.sh` by the CI scripts
+## when a new commit lands on `master` (i.e., after it passed all checks on `auto`).
+
 import sys
 import re
 import os