+#
+# Policy hook scripts are invoked like this:
+# POLICY-HOOK-SCRIPT DISTRO DGIT-REPOS-DIR DGIT-LIVE-DIR DISTRO-DIR ACTION...
+# ie.
+# POLICY-HOOK-SCRIPT ... check-list [...]
+# POLICY-HOOK-SCRIPT ... check-package PACKAGE [...]
+# POLICY-HOOK-SCRIPT ... push PACKAGE \
+# VERSION SUITE TAGNAME DELIBERATELIES [...]
+# POLICY-HOOK-SCRIPT ... push-confirm PACKAGE \
+# VERSION SUITE TAGNAME DELIBERATELIES FRESH-REPO|'' [...]
+#
+# DELIBERATELIES is like this: --deliberately-foo,--deliberately-bar,...
+#
+# Exit status of policy hook 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)
+# NOCOMMITCHECK (8)
+# suppress dgit-repos-server's check that commits do
+# not lack "committer" info (eg as produced by #849041)
+# ("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 incoming
+# objects have been received; TAGNAME is the version-based tag.
+#
+# FRESH-REPO is '' iff the repo for this package already existed, or
+# the pathname of the newly-created repo which will be renamed into
+# place if everything goes well. (NB that this is generally not the
+# same repo as the cwd, because the objects are first received into a
+# temporary repo so they can be examined.) In this case FRESH-REPO
+# contains exactly the objects and refs that will appear in the
+# destination if push-confirm approves.
+#
+# if push requested FRESHREPO, push-confirm happens in the old working
+# repo and FRESH-REPO is guaranteed not to be ''.
+#
+# policy hook for a particular package will be invoked only once at
+# a time - (see comments about DGIT-REPOS-DIR, above)
+#
+# check-list and check-package are invoked via the --cron option.
+# First, without any locking, check-list is called. It should produce
+# a list of package names (one per line). Then check-package will be
+# invoked for each named package, in each case after taking an
+# appropriate lock.
+#
+# If policy hook wants to run dgit (or something else in the dgit
+# package), it should use DGIT-LIVE-DIR/dgit (etc.), or if that is
+# ENOENT, use the installed version.
+#
+# Mirror hook scripts are invoked like this:
+# MIRROR-HOOK-SCRIPT DISTRO-DIR ACTION...
+# and currently there is only one action invoked by dgit-repos-server:
+# MIRROR-HOOK-SCRIPT DISTRO-DIR updated-hook PACKAGE [...]
+#
+# Exit status of the mirror hook is advisory only. The mirror hook
+# runs too late to do anything useful about a problem, so the only
+# effect of a mirror hook exiting nonzero is a warning message to
+# stderr (which the pushing user should end up seeing).
+#
+# If the mirror hook does not exist, it is silently skipped.