NAME¶
SVN::Hooks::CheckJira - Integrate Subversion with the JIRA ticketing system.
VERSION¶
version 1.27
DESCRIPTION¶
This SVN::Hooks plugin requires that any Subversion commits affecting some parts
of the repository structure must make reference to valid JIRA issues in the
commit log message. JIRA issues are referenced by their keys which consists of
a sequence of uppercase letters separated by an hyfen from a sequence of
digits. E.g., CDS-123, RT-1, and SVN-97.
It's active in the "pre-commit" and/or the "post-commit"
hook.
It's configured by the following directives.
CHECK_JIRA_CONFIG(BASEURL, LOGIN, PASSWORD [, REGEXP [, REGEXP]])¶
This directive specifies how to connect and to authenticate to the JIRA server.
BASEURL is the base URL of the JIRA server, usually, something like
"
http://jira.example.com/jira". LOGIN and PASSWORD are the
credentials of a JIRA user who has browsing rights to the JIRA projects that
will be referenced in the commit logs.
The fourth argument is an optional qr/Regexp/ object. It will be used to match
against the commit logs in order to extract the list of JIRA issue keys. By
default, the JIRA keys are looked for in the whole commit log, which is
equivalent to qr/(.*)/. Sometimes this can be suboptimal because the user can
introduce in the message some text that inadvertently looks like a JIRA issue
key whithout being so. With this argument, the log message is matched against
the REGEXP and only the first matched group (i.e., the part of the message
captured by the first parenthesis ($1)) is used to look for JIRA issue keys.
The fifth argument is another optional qr/Regexp/ object. It is used to match
JIRA project keys, which match qr/[A-Z]{2,}/ by default. However, since you
can specify different patterns for JIRA project keys
(<
http://confluence.atlassian.com/display/JIRA/Configuring+Project+Keys>),
you need to be able to specify this here too.
The JIRA issue keys are extracted from the commit log (or the part of it
specified by the REGEXP) with the following pattern:
"qr/\b([A-Z]+-\d+)\b/g";
CHECK_JIRA(REGEXP => {OPT => VALUE, ...})¶
This directive tells how each part of the repository structure must be
integrated with JIRA.
During a commit, all files being changed are tested against the REGEXP of each
CHECK_JIRA directive, in the order that they were called. If at least one
changed file matches a regexp, the issues cited in the commit log are checked
against their current status on JIRA according to the options specified after
the REGEXP.
The available options are the following:
- projects => 'PROJKEYS'
- By default, the commiter can reference any JIRA issue in the commit log.
You can restrict the allowed keys to a set of JIRA projects by specifying
a comma-separated list of project keys to this option.
- require => [01]
- By default, the log must reference at least one JIRA issue. You can make
the reference optional by passing a false value to this option.
- valid => [01]
- By default, every issue referenced must be valid, i.e., it must exist on
the JIRA server. You can relax this requirement by passing a false value
to this option. (Why would you want to do that, though?)
- unresolved => [01]
- By default, every issue referenced must be unresolved, i.e., it must not
have a resolution. You can relax this requirement by passing a false value
to this option.
- by_assignee => [01]
- By default, the commiter can reference any valid JIRA issue. Passing a
true value to this option you require that the commiter can only reference
issues to which she is the current assignee.
- check_one => CODE-REF
- If the above checks aren't enough you can pass a code reference
(subroutine) to this option. The subroutine will be called once for each
referenced issue with three arguments:
- the JIRA::Client object used to talk to the JIRA server.
- the RemoteIssue object representing the issue.
- the SVN::Look object used to grok information about the commit.
The subroutine must simply return with no value to indicate success and must die
to indicate failure.
Plese, read the JIRA::Client and SVN::Look modules documentation to understand
how to use these objects.
- check_all => CODE-REF
- Sometimes checking each issue separatelly isn't enough. You may want to
check some relation among all the referenced issues. In this case, pass a
code reference to this option. It will be called once for the commit. Its
first argument is the JIRA::Client object used to talk to the JIRA server.
The following arguments are references to RemoteIssue objects for every
referenced issue. The last argument is the SVN::Look object used to grok
information about the commit. The subroutine must simply return with no
value to indicate success and must die to indicate failure.
- check_all_svnlook => CODE-REF
- This check is the same as the previous one, except that the first argument
passed to the routine is the SVN::Look object used to grok information
about the commit. The rest of the arguments are the same.
- post_action => CODE-REF
- This is not a check, but an opportunity to perform some action after a
successful commit. The code reference passed will be called once during
the post-commit hook phase. Its first argument is the JIRA::Client object
used to talk to the JIRA server. The second argument is the SVN::Look
object that can be used to inspect all the information about the commit
proper. The following arguments are the JIRA keys mentioned in the commit
log message. The value returned by the routine, if any, is ignored.
- exclude => REGEXP
- Normally you specify a CHECK_JIRA with a regex matching a root directory
in the repository hierarchy. Sometimes you need to specify some subparts
of that root directory that shouldn't be treated by this CHECK_JIRA
directive. You can use this option to specify these exclusions by means of
another regex.
You can set defaults for these options using a CHECK_JIRA directive with the
string 'default' as a first argument, instead of a qr/Regexp/.
# Set some defaults
CHECK_JIRA(default => {
projects => 'CDS,TST',
by_assignee => 1,
});
# Check if some commits are scheduled, i.e., if they reference
# JIRA issues that have at least one fix version.
sub is_scheduled {
my ($jira, $issue, $svnlook) = @_;
return scalar @{$issue->{fixVersions}};
}
CHECK_JIRA(qr/^(trunk|branches/fix)/ => {
check_one => \&is_scheduled,
});
Note that you need to call CHECK_JIRA at least once with a qr/Regexp/ in order
to trigger the checks. A call for ('default' doesn't count. If you want to
change defaults and force checks for every commit, do this:
CHECK_JIRA(default => {projects => 'CDS'});
CHECK_JIRA(qr/./);
The 'post_action' pseudo-check can be used to interact with the JIRA server
after a successful commit. For instance, you may want to add a comment to each
refered issue like this:
# This routine returns a closure that can be passed to
# post_action. The closure receives a string to be added as a
# comment to each issue refered to by the commit message. The
# commit info can be interpolated inside the comment using the
# SVN::Look method names inside angle brackets.
sub add_comment {
my ($format) = @_;
return sub {
my ($jira, $svnlook, @keys) = @_;
# Substitute keywords in the input comment with calls
# into the $svnlook reference
$format =~ s/\{(\w+)\}/"\$svnlook->$1()"/eeg;
for my $key (@keys) {
$jira->addComment($key, $format);
}
}
}
CHECK_JIRA(qr/./ => {
post_action => add_comment("Subversion Commit r{rev} by {author} on {date}\n{log_msg}")
});
You can use a generic CHECK_JIRA excluding specific directories from it using
the "exclude" option like this:
CHECK_JIRA(qr:^(trunk|branches/[^/]): => {
exclude => qr:/documentation/:,
# other options...
});
CHECK_JIRA_DISABLE¶
This directive globally disables all CHECK_JIRA directives. It's useful, for
instance, when your JIRA server must be taken down for maintenance and you
don't want to reject Subversion commits in this period.
AUTHOR¶
Gustavo L. de M. Chaves <gnustavo@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by CPqD.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.