NAME

App::KGB::Client - relay commits to KGB servers

SYNOPSIS

use App::KGB::Client;
my $client = App::KGB::Client( <parameters> );
$client->run;

DESCRIPTION

App::KGB::Client is the backend behind kgb-client(1). It handles the repository-independent parts of sending the notifications to the KGB server, kgb-bot(1). Details about extracting change from commits, branches and modules is done by sub-classes specific to the version control system in use.

CONFIGURATION

The following parameters are accepted in the constructor:

repo_id repository name

Short repository identifier. Will be used for identifying the repository to the KGB daemon, which will also use this for IRC notifications. Mandatory.

uri URI

URI of the KGB server. Something like http://some.server:port. Mandatory either as a top-level parameter or as a sub-parameter of servers array.

proxy URI

URI of the SOAP proxy. If not given, it is the value of the uri option, with ?session=KGB added.

password password

Password for authentication to the KGB server. Mandatory either as a top-level parameter or as a sub-parameter of servers array.

timeout seconds

Timeout for server communication. Default is 15 seconds, as we want instant IRC and commit response.

servers

An array of servers, each an instance of App::KGB::Client::ServerRef class.

When several servers are configured, the list is shuffled and then the servers are tried one after another until a successful request is done, or the list is exhausted, in which case an exception is thrown.

br_mod_re

A list of regular expressions (simple strings, not qr objects) that serve 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 order for the branch and module to be transmitted to the KGB server.

Example: ([^/]+)/([^/]+)/
         # branch/module

br_mod_re_swap 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 kgb-client.

ignore_branch

When most of the development is in one branch, transmitting it to the KGB server and seeing it on ORC all the time can be annoing. Therefore, if you define ignore_branch, and a given commit is in a branch with that name, the branch name is not transmitted to the server. Module name is still transmitted.

module

Forces explicit module name, overriding the branch and module detection. Useful in Git-hosted sub-projects that want to share single configuration file, but still want module indication in notifications.

verbose

Print diagnostic information.

CONSTRUCTOR

new ( { initial values } )

Standard constructor with initial values in a hashref.

my $c = App::KGB::Client->new(
    {   repo_id => 'my-repo',
        servers => \@servers,
        ...
    }
);

See above.

METHODS

detect_branch_and_module ( $changes )

Given a set of changes (an arrayref of App::KGB::Change objects), runs all the regular expressions as listed in br_mod_re and if a regular expression that matches all the changed paths and returns the branch and module.

In case the module detected is the same as ignore_module, undef is returned for module.

( $branch, $module ) = $client->detect_branch_and_module($changes);

process_commit ($commit)

Processes a single commit, trying to send the changes summary to each of the servers, defined inn servers, until some server is successfuly notified.

process

The main processing method. Calls describe_commit and while it returns true values, gives them to process_commit.

PROVIDING REPOSITORY-SPECIFIC FUNCTIONALITY

App::KGB::Client is a generic class providing repository-agnostic functionality. All repository-specific methods are to be provided by classes, inheriting from App::KGB::Client. See App::KGB::Client::Subversion and App::KGB::Client::Git.

Repository classes must provide the following method:

dsescribe_commit

This method returns an App::KGB::Commit object that represents a single commit of the repository.

describe_commit is called several times, until it returns undef. The idea is that a single App::KGB::Client run can be used to process several commits (for example if the repository is Git). If this is the case each call to describe_commit shall return information about the next commit in the series. For Subversion, this module is expected to return only one commit, subsequent calls shall return undef.

SEE ALSO

App::KGB::Client::Subversion

App::KGB::Client::Git