r43815 - /scripts/KGB/client/KGB_sendcommit

[dmn at users.alioth.debian.org]

Author: dmn
Date: Mon Sep  7 14:05:09 2009
New Revision: 43815

URL: http://svn.debian.org/wsvn/?sc=1&rev=43815
Log:
document KGB client

Modified:
    scripts/KGB/client/KGB_sendcommit

Modified: scripts/KGB/client/KGB_sendcommit
URL: http://svn.debian.org/wsvn/scripts/KGB/client/KGB_sendcommit?rev=43815&op=diff
==============================================================================
--- scripts/KGB/client/KGB_sendcommit (original)
+++ scripts/KGB/client/KGB_sendcommit Mon Sep  7 14:05:09 2009
@@ -24,6 +24,137 @@
 use strict;
 use warnings;
 
+=head1 NAME
+
+kgb-client - relay commits to KGB servers
+
+=head1 SYNOPSIS
+
+    B<kgb-client> I<option>... I<SVN repo path> I<revision>
+
+    B<kgb-client> --conf I</path/to/configuration> [I<other option> ...]
+    B<kgb-client> --uri I<http://some.server:port/service>
+                  --repo-id I<repository>
+                  --timeout I<timeout in seconds>
+
+=head1 DESCRIPTION
+
+B<kgb-client> is the client counterpart of L<kgb-bot(1)>. Intented usage is as
+a post-commit hook in your version control system. It analyzes the commit(s)
+and then relays the information about the repository, branch, author, modified
+filed and change log to the KGB server, who will show it on IRC.
+
+=head1 CONFIGURATION
+
+=over
+
+=item B<--conf> I<configuration file>
+
+Specifies the path to kgb-client configuration file.
+
+=back
+
+Configuration options (except B<--conf>) may be specified both in the
+configuration file and on the command line. Usually you want to have all the
+options in a configuration file, because having passwords on the command line
+is insecure. The configuration file also gives more control, for example it
+supports multple servers and multiple ways of detection of branch and module
+names.
+
+The configration file is in L<YAML> format. Unless noted otherwise, all the
+options below can be used on the command line if prepended with two dashes. An
+example configuration file is shipped with the distribution.
+
+=over
+
+=item B<repository> I<type>
+
+Specifies the type of the repository B<kgb-client> shall be working with.
+Currently defaults to C<svn>.
+
+=item B<repo-id> I<repository name>
+
+Short repository identifier. Will be used for identifying the repository to the
+KGB daemon, which will also use this for IRC notifications. B<Mandatory>.
+
+=item B<uri> I<URI>
+
+URI of the KGB server. Something like C<http://some.server:port>. B<Mandatory>.
+
+=item B<proxy> I<URI>
+
+URI of the SOAP proxy. If not given, it is the value of the B<uri> option, with
+C<?session=KGB> added.
+
+=item B<password> I<password>
+
+Password for authentication to the KGB server.
+
+=item B<timeout> I<seconds>
+
+Timeout for server communication. Default is 15 seconds, as we want instant IRC
+and commit response.
+
+=item B<servers>
+
+Only available in the configuration file.
+
+An array of servers, each described using B<uri>, B<proxy>, B<password> and
+B<timeout> options. When several servers are configured, B<kgb-client> chooses
+one randomly. If a given server times out or there is another problem with
+communication, B<kgb-client> tries another server.
+
+The top-level B<uri>, B<proxy>, B<password> and B<timeout> options are treated
+as describing an extra server to the servers described in B<servers> array.
+
+The B<password> and B<timeout> options default too the top-level options of the
+same name.
+
+=item B<branch-and-module-re>
+
+A list of regular expressions thet server for detection of branch and module of
+commits. Each item from the list is tried in turn, until an item is found that
+matches all the paths that were modified by the commit. Regular expressions
+must have two captures: the first one giving the branch name, and the second
+one giving the module name.
+
+All the paths that were modified by the commit must resolve to the same branch
+and module in orderfor the branch and module to be transmitted to the KGB
+server.
+
+=item B<branch-and-module-re-swap> I<1>
+
+If you can only provide the module name in the first capture and the branch
+name in the second, use this option to signal the fact to B<kgb-client>.
+
+=back
+
+=head1 SUPPORTED VERSION CONTROL SYSTEMS
+
+=head2 Subversion
+
+Installation requires calling B<kgb-client> with two command line arguments:
+
+=over
+
+=item I<path to the subversion repository>
+
+This is the physical path to the Subversion repository. Something like I</srv/svn/my-repo>
+
+=item I<revision>
+
+This is the revision number of the commit, that has triggered the hook.
+
+=back
+
+Both these arguments are supplied to the standard Subversion post-commit hooks.
+
+=head2 Git
+
+TODO
+
+=cut
+
 use Digest::SHA1 qw(sha1_hex);
 use SOAP::Lite;
 use Getopt::Long;