X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=infra%2Fdgit-repos-server;h=acff1727541491ace4bfc45ba4e56a63a7e40c84;hp=9c4859db4eba73f068e29d66c12d222388e95ae8;hb=66ca07a7e81a379bd745647d239761087c40288c;hpb=48f18b95adcd0f9c1d5a9a204126e845d116d44f

diff --git a/infra/dgit-repos-server b/infra/dgit-repos-server
index 9c4859db..acff1727 100755
--- a/infra/dgit-repos-server
+++ b/infra/dgit-repos-server
@@ -34,6 +34,8 @@ use strict;
 #  PACKAGE_garbage                  }   (also covers executions of
 #  PACKAGE_garbage-old              }    policy hook script for PACKAGE)
 #  PACKAGE_garbage-tmp              }
+#  policy*                          } (for policy hook script, covered by
+#                                   }  lock only when invoked for a package)
 #
 # leaf locks, held during brief operaton only:
 #
@@ -105,6 +107,35 @@ use strict;
 #    the corresponding temporary tree, as the lockfile is also
 #    a stampfile whose presence indicates that there may be
 #    cleanup to do
+#
+# Policy hook script is invoked like this:
+#   POLICY-HOOK-SCRIPT DISTRO DGIT-REPOS-DIR ACTION...
+# ie.
+#   POLICY-HOOK-SCRIPT ... check-list [...]
+#   POLICY-HOOK-SCRIPT ... check-package PACKAGE [...]
+#   POLICY-HOOK-SCRIPT ... push|push-confirm PACKAGE \
+#         VERSION SUITE TAGNAME DELIBERATELIES [...]
+#
+# Exit status is a bitmask.  Bit weight constants are defined in Dgit.pm.
+#    NOFFCHECK   (2)
+#         suppress dgit-repos-server's fast-forward check ("push" only)
+#    FRESHREPO   (4)
+#         blow away repo right away (ie, as if before push or fetch)
+#         ("check-package" and "push" only)
+# any unexpected bits mean failure, and then known set bits are ignored
+# if no unexpected bits set, operation continues (subject to meaning
+# of any expected bits set).  So, eg, exit 0 means "continue normally"
+# and would be appropriate for an unknown action.
+#
+# cwd for push and push-confirm is a temporary repo where the
+# to-be-pushed objects have been received; TAGNAME is the
+# version-based tag
+#
+# if push requested FRESHREPO, push-confirm happens in said fresh repo
+#
+# policy hook for a particular package will be invoked only once at
+# a time - (see comments about DGIT-REPOS-DIR, above)
+
 
 use POSIX;
 use Fcntl qw(:flock);