From af28a5e898af844421b60bac4a8f897d3b5965eb Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <marcello.stanisci@inria.fr>
Date: Thu, 19 Oct 2017 13:04:32 +0200
Subject: instructions on buildbot+(git)hooks

---
 doc/onboarding.texi | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

(limited to 'doc/onboarding.texi')

diff --git a/doc/onboarding.texi b/doc/onboarding.texi
index 7b16dde..f1376f9 100644
--- a/doc/onboarding.texi
+++ b/doc/onboarding.texi
@@ -250,7 +250,8 @@ log-in as @emph{test} and run the script @code{$HOME/.ln-<COLOR>.sh}, in order t
 
 @subsection Website lcov.taler.net
 
-The directory @code{/var/www/lcov.taler.net} contains the following two symlinks
+The directory @code{/var/www/lcov.taler.net} contains the following
+two symlinks
 
 @itemize
 @item exchange --> @code{/home/lcovslave/exchange/doc/coverage}
@@ -259,6 +260,53 @@ The directory @code{/var/www/lcov.taler.net} contains the following two symlinks
 
 The pointed locations are updated by the @emph{lcovslave}.
 
+@subsection Hooks
+
+@cartouche
+@quotation Note
+Hooks at taler.net are still work in progress, so this section should
+be considered a recipe, rather than a fact.
+@end quotation
+@end cartouche
+
+Whenever a push occurs into one of Taler repositories, Buildbot gets
+notified via the Git @emph{hooks} system.
+
+We use a patched version of the following Git hook [1].
+
+The patch allows the script to extract the @emph{project} keyword
+from the repository.  Depending on this keyword, the Buildbot's
+scheduler will then perform or not the compilation.
+
+Following a @emph{gitolite}-policy, all the hook must be committed under
+@code{gitolite-admin/local/hooks/repo-specific/post-receive.buildbot},
+so that gitolite will copy it in the right place -- the sysadmin does @strong{not}
+have to manually move it.
+
+Once the hook is versioned under gitolite, every repository meant to benefit
+from it must get the @code{option hook.pre-receive = pre-receive.buildbot}
+statement from the gitolite config file.
+
+On the Buildbot side, we need to allow the hook to connect to the build master.
+This is done by defining a @code{PBChangeSource} class in the following way:
+@example
+cs = changes.PBChangeSource(user='tony', passwd='hey')
+@end example
+NOTE: those credentials must match the ones within the hook; search for the
+@code{UsernamePassoword} class in the hook.
+
+The following line will finally "activate" the hook within the build master:
+@example
+c['change_source'].append(cs)
+@end example
+
+From now on, every buildbot scheduler will receive notifications from @code{cs}
+and verify if there is a match with the @code{ChangeFilter} driving the scheduler.
+If there is a match, the scheduler will fire its builders up, otherwise no action
+is taken.
+
+[1]: @url{https://github.com/djmitche/buildbot/blob/d4ec886c3740a4f97a
+b172b81c9a9b94eb6f00d3/contrib/git_buildbot.py}.
 
 @node Standalone deployment
 @chapter Standalone deployment
-- 
cgit v1.2.3