{"thread":{"id":"31327","subject":"[PATCH] Improved documentation for the ciabot scripts.","startedAt":"2012-08-23T04:10:53Z","lastAt":"2012-08-23T04:10:53Z","messageCount":1,"participants":["Eric S. Raymond"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"197675","messageId":"20120823041053.GA11353@thyrsus.com","threadId":"31327","inReplyTo":null,"subject":"[PATCH] Improved documentation for the ciabot scripts.","fromName":"Eric S. Raymond","fromEmail":"esr@thyrsus.com","sentAt":"2012-08-23T04:10:53Z","receivedAt":"2012-08-23T04:10:53Z","isPatch":true,"sender":{"key":"esr@thyrsus.com","avatar":"https://avatars.githubusercontent.com/u/727961?v=4"},"body":"Signed-off-by: Eric S. Raymond <esr@thyrsus.com>\n---\n contrib/ciabot/INSTALL |   39 +++++++++++++++++++++++++++++++++++++++\n contrib/ciabot/README  |   14 ++++++++++++--\n 2 files changed, 51 insertions(+), 2 deletions(-)\n create mode 100644 contrib/ciabot/INSTALL\n\ndiff --git a/contrib/ciabot/INSTALL b/contrib/ciabot/INSTALL\nnew file mode 100644\nindex 0000000..dbfd165\n--- /dev/null\n+++ b/contrib/ciabot/INSTALL\n@@ -0,0 +1,39 @@\n+= Installation instructions =\n+\n+Two scripts are included.  The Python one (ciabot.py) is faster and\n+more capable; the shell one (ciabot.sh) is a fallback in case Python\n+gives your git hosting site indigestion. (I know of no such sites.)\n+\n+It is no longer necessary to modify the script in order to put it\n+in place; in fact, this is now discouraged. It is entirely\n+configurable with the following git config variables:\n+\n+ciabot.project = name of the project (required)\n+ciabot.repo = name of the project repo for gitweb/cgit purposes\n+ciabot.xmlrpc  = if true (default), ship notifications via XML-RPC\n+ciabot.revformat = format in which the revision is shown\n+\n+The ciabot.repo value defaults to ciabot.project lowercased.\n+\n+The revformat variable may have the following values\n+raw -> full hex ID of commit\n+short -> first 12 chars of hex ID\n+describe -> describe relative to last tag, falling back to short\n+The default is 'describe'.\n+\n+Once you've set these variables, try your script with -n to see the\n+notification message dumped to stdout and verify that it looks sane.\n+\n+After verifying correct function, install one of these scripts either\n+in a post-commit hook or in an update hook.\n+\n+In post-commit, run it without arguments. It will query for\n+current HEAD and the latest commit ID to get the information it\n+needs.\n+\n+In update, call it with a refname followed by a list of commits:\n+You want to reverse the order git rev-list emits because it lists\n+from most recent to oldest.\n+\n+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)\n+\ndiff --git a/contrib/ciabot/README b/contrib/ciabot/README\nindex 3b916ac..9eccca3 100644\n--- a/contrib/ciabot/README\n+++ b/contrib/ciabot/README\n@@ -8,5 +8,15 @@ You probably want the Python version; it's faster, more capable, and\n better documented.  The shell version is maintained only as a fallback\n for use on hosting sites that don't permit Python hook scripts.\n \n-You will find installation instructions for each script in its comment\n-header.\n+To test these scripts, your project needs to have been registered with\n+the CIA site.  Here are the steps:\n+\n+1. Open an IRC window on irc://freenode/commits or your registered \n+   project IRC channel.  \n+\n+2. Run ciabot.py and/or ciabot.sh from any directory under git\n+   control, using the -p option to pass in your project name.\n+\n+You should see a notification on the channel for your most recent commit.\n+\n+See the file INSTALL for installation instructions.\n-- \n1.7.9.5\n\n-- \n\t\t<a href=\"http://www.catb.org/~esr/\">Eric S. Raymond</a>\n"}]}