dgit-repos-policy-debian: Add some promises about check_package

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

1 files changed, 15 insertions, 0 deletions

diff --git a/infra/dgit-repos-policy-debian b/infra/dgit-repos-policy-debian
index cbad36e..9c92706 100755
--- a/infra/dgit-repos-policy-debian
+++ b/infra/dgit-repos-policy-debian
@@ -247,6 +247,21 @@ sub add_taint_by_tag ($$) {
 }
 
 sub check_package () {
+    # This is not read-only, but it is safe to call within a
+    # policy-client-query, because it will do one of the following:
+    #
+    #  * Do nothing much.
+    #  * Find that the package has been ACCEPTed, make it not secret,
+    #    and mirror it.
+    #  * Find that the package has been REJECTed and add some taints
+    #    to the db.  This may be rolled back, but that's OK because
+    #    future calls will discover the same.
+    #
+    # (This is a consequence of this function being idempotent,
+    # cron-callable, and correct in the sense that it doesn't make
+    # wrongly-sequenced updates to both the DB and the FS.)
+    #
+    # An (often useful) side-effect is to chdir to the package repo.
     return 0 unless $pkg_exists;
     return 0 unless $pkg_secret;