[no subject]

[Ludovic Courtès]

branch: master
commit a057228492b6dfdb94d249088982de7cb289d5b3
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Wed Sep 6 23:39:25 2023 +0200

    database: Document the pitfalls of ‘db-get-checkouts’.
    
    * src/cuirass/base.scm (latest-checkouts): Improve docstring.
    * src/cuirass/database.scm (db-get-checkouts): Add docstring.
---
 src/cuirass/base.scm     | 5 +++--
 src/cuirass/database.scm | 6 ++++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/cuirass/base.scm b/src/cuirass/base.scm
index 075c49d..b96730b 100644
--- a/src/cuirass/base.scm
+++ b/src/cuirass/base.scm
@@ -640,8 +640,9 @@ OUTPUTS, a list of <build-output> records."
     (apply latest-channel-instances args)))
 
 (define (latest-checkouts spec eval-id)
-  "Return the latest checkouts for the EVAL-ID evaluation of the SPEC
-specification."
+  "Return the complete list of checkouts used for the EVAL-ID evaluation of
+SPEC (as opposed to 'db-get-checkouts', which only returns checkouts that
+different from the previous evaluation of SPEC)."
   (let ((name (specification-name spec))
         (channels (specification-channels spec)))
     (map (lambda (channel)
diff --git a/src/cuirass/database.scm b/src/cuirass/database.scm
index 4590864..f08426b 100644
--- a/src/cuirass/database.scm
+++ b/src/cuirass/database.scm
@@ -1613,6 +1613,12 @@ SELECT id FROM pending_dependencies WHERE deps = 0 LIMIT 
1;"))
   (directory checkout-directory))
 
 (define (db-get-checkouts eval-id)
+  "Return the list of checkouts *changed* in EVAL-ID.
+
+For example, if channel A moved from one commit to another, triggering
+EVAL-ID, then channel A is returned.  But perhaps EVAL-ID also depends on
+channels B and C, which are not returned here because they haven't changed
+compared to the previous evaluation of this jobset."
   (with-db-worker-thread db
     (let loop ((rows (exec-query/bind
                       db "SELECT revision, channel, directory FROM Checkouts