From d395baaa070686dce79a9ad7cd02777a4caa4778 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 22 Mar 2015 10:30:23 +0000
Subject: [PATCH] Repos policy machinery: better docs, etc.

---
 Debian/Dgit.pm                 | 11 +++--------
 infra/dgit-repos-policy-debian | 24 ++++--------------------
 infra/dgit-repos-server        | 31 +++++++++++++++++++++++++++++++
 3 files changed, 38 insertions(+), 28 deletions(-)

diff --git a/Debian/Dgit.pm b/Debian/Dgit.pm
index e2f8edd0..6932d14a 100644
--- a/Debian/Dgit.pm
+++ b/Debian/Dgit.pm
@@ -23,17 +23,12 @@ our @EXPORT_OK;
 our $package_re = '[0-9a-z][-+.0-9a-z]*';
 our $branchprefix = 'dgit';
 
-
 # policy hook exit status bits
-# any unexpected bits mean failure, and then known set bits are ignored
-
+# see dgit-repos-server head comment for documentation
+# 1 is reserved in case something fails with `exit 1'
 sub NOFFCHECK () { return 2; }
-# suppress dgit-repos-server's ff check ("push" only)
-
 sub FRESHREPO () { return 4; }
-# blow away repo right away (ie, as if before push or fetch)
-# ("check-package" and "push" only)
-
+# 128 is reserved
 
 sub debiantag ($) { 
     my ($v) = @_;
diff --git a/infra/dgit-repos-policy-debian b/infra/dgit-repos-policy-debian
index 5724c938..c84fd7d4 100755
--- a/infra/dgit-repos-policy-debian
+++ b/infra/dgit-repos-policy-debian
@@ -1,23 +1,5 @@
 #!/usr/bin/perl -w
 # dgit repos policy hook script for Debian
-#
-# usages:
-#   dgit-repos-policy-debian DISTRO DGIT-REPOS-DIR ACTION...
-# ie.
-#   dgit-repos-policy-debian ... check-list [...]
-#   dgit-repos-policy-debian ... check-package PACKAGE [...]
-#   dgit-repos-policy-debian ... push PACKAGE \
-#         VERSION SUITE TAGNAME DELIBERATELIES [...]
-#   dgit-repos-policy-debian ... push-confirm PACKAGE \
-#         VERSION SUITE TAGNAME DELIBERATELIES [...]
-#
-# cwd for push 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
 
 use strict;
 use POSIX;
@@ -31,7 +13,7 @@ our $repos = shift @ARGV // die "need DGIT-REPOS-DIR";
 our $action = shift @ARGV // die "need ACTION";
 
 our $publicmode = 02775;
-our $policydb = "dbi:SQLite:$repos/policy";
+our $policydb = "dbi:SQLite:$repos/policy.sqlite3";
 our $new_upload_propagation_slop = 3600*4 + 100;
 
 our $poldbh;
@@ -398,7 +380,9 @@ if (defined $pkg) {
 
 $cmd =~ y/-/_/;
 my $fn = ${*::}{"action__$cmd"};
-$fn or die "unknown ACTION";
+if (!$fn) {
+    exit 0;
+}
 
 poldb_setup();
 
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);
-- 
2.30.2