Improved documentation for the ciabot scripts.
Signed-off-by: Eric S. Raymond <esr@thyrsus.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Eric S. Raymond committed
Aug 23, 2012 at 00:10 UTC
64840701683b4126234b39da746b3cddb6db00a8
2 files changed
+50
-2
contrib/ciabot/INSTALL
new
+38
@@ -0,0 +1,38 @@
1
+= Installation instructions =
2
+
3
+Two scripts are included. The Python one (ciabot.py) is faster and
4
+more capable; the shell one (ciabot.sh) is a fallback in case Python
5
+gives your git hosting site indigestion. (I know of no such sites.)
6
+
7
+It is no longer necessary to modify the script in order to put it
8
+in place; in fact, this is now discouraged. It is entirely
9
+configurable with the following git config variables:
10
+
11
+ciabot.project = name of the project (required)
12
+ciabot.repo = name of the project repo for gitweb/cgit purposes
13
+ciabot.xmlrpc = if true (default), ship notifications via XML-RPC
14
+ciabot.revformat = format in which the revision is shown
15
+
16
+The ciabot.repo value defaults to ciabot.project lowercased.
17
+
18
+The revformat variable may have the following values
19
+raw -> full hex ID of commit
20
+short -> first 12 chars of hex ID
21
+describe -> describe relative to last tag, falling back to short
22
+The default is 'describe'.
23
+
24
+Once you've set these variables, try your script with -n to see the
25
+notification message dumped to stdout and verify that it looks sane.
26
+
27
+After verifying correct function, install one of these scripts either
28
+in a post-commit hook or in an update hook.
29
+
30
+In post-commit, run it without arguments. It will query for
31
+current HEAD and the latest commit ID to get the information it
32
+needs.
33
+
34
+In update, call it with a refname followed by a list of commits:
35
+You want to reverse the order git rev-list emits because it lists
36
+from most recent to oldest.
37
+
38
+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
contrib/ciabot/README
+12
-2
@@ -8,5 +8,15 @@ You probably want the Python version; it's faster, more capable, and
8
better documented. The shell version is maintained only as a fallback
9
for use on hosting sites that don't permit Python hook scripts.
10
11
-You will find installation instructions for each script in its comment
12
-header.
11
+To test these scripts, your project needs to have been registered with
12
+the CIA site. Here are the steps:
13
+
14
+1. Open an IRC window on irc://freenode/commits or your registered
15
+ project IRC channel.
16
+
17
+2. Run ciabot.py and/or ciabot.sh from any directory under git
18
+ control, using the -p option to pass in your project name.
19
+
20
+You should see a notification on the channel for your most recent commit.
21
+
22
+See the file INSTALL for installation instructions.