.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "SVN::Hooks::CheckJira 3pm" .TH SVN::Hooks::CheckJira 3pm "2017-06-24" "perl v5.24.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" SVN::Hooks::CheckJira \- Integrate Subversion with the JIRA ticketing system. .SH "VERSION" .IX Header "VERSION" version 1.34 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This SVN::Hooks plugin requires that any Subversion commits affecting some parts of the repository structure must make reference to valid \&\s-1JIRA\s0 issues in the commit log message. \s-1JIRA\s0 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., \s-1CDS\-123, RT\-1,\s0 and \&\s-1SVN\-97.\s0 .PP It's active in the \f(CW\*(C`pre\-commit\*(C'\fR and/or the \f(CW\*(C`post\-commit\*(C'\fR hook. .PP It's configured by the following directives. .SS "\s-1CHECK_JIRA_CONFIG\s0(\s-1BASEURL, LOGIN, PASSWORD\s0 [, \s-1REGEXP\s0 [, \s-1REGEXP\s0]])" .IX Subsection "CHECK_JIRA_CONFIG(BASEURL, LOGIN, PASSWORD [, REGEXP [, REGEXP]])" This directive specifies how to connect and to authenticate to the \&\s-1JIRA\s0 server. \s-1BASEURL\s0 is the base \s-1URL\s0 of the \s-1JIRA\s0 server, usually, something like \f(CW\*(C`http://jira.example.com/jira\*(C'\fR. \s-1LOGIN\s0 and \s-1PASSWORD\s0 are the credentials of a \s-1JIRA\s0 user who has browsing rights to the \s-1JIRA\s0 projects that will be referenced in the commit logs. .PP 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 \s-1JIRA\s0 issue keys. By default, the \s-1JIRA\s0 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 \s-1JIRA\s0 issue key without being so. With this argument, the log message is matched against the \s-1REGEXP\s0 and only the first matched group (i.e., the part of the message captured by the first parenthesis (\f(CW$1\fR)) is used to look for \s-1JIRA\s0 issue keys. .PP The fifth argument is another optional qr/Regexp/ object. It is used to match \s-1JIRA\s0 project keys, which match qr/[A\-Z]{2,}/ by default. However, since you can specify different patterns for \s-1JIRA\s0 project keys (), you need to be able to specify this here too. .PP The \s-1JIRA\s0 issue keys are extracted from the commit log (or the part of it specified by the \s-1REGEXP\s0) with the following pattern: \&\f(CW\*(C`qr/\eb([A\-Z]+\-\ed+)\eb/g\*(C'\fR; .SS "\s-1CHECK_JIRA\s0(\s-1REGEXP\s0 => {\s-1OPT\s0 => \s-1VALUE, ...\s0})" .IX Subsection "CHECK_JIRA(REGEXP => {OPT => VALUE, ...})" This directive tells how each part of the repository structure must be integrated with \s-1JIRA.\s0 .PP During a commit, all files being changed are tested against the \s-1REGEXP\s0 of each \s-1CHECK_JIRA\s0 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 \s-1JIRA\s0 according to the options specified after the \s-1REGEXP.\s0 .PP The available options are the following: .IP "projects => '\s-1PROJKEYS\s0'" 4 .IX Item "projects => 'PROJKEYS'" By default, the committer can reference any \s-1JIRA\s0 issue in the commit log. You can restrict the allowed keys to a set of \s-1JIRA\s0 projects by specifying a comma-separated list of project keys to this option. .IP "require => [01]" 4 .IX Item "require => [01]" By default, the log must reference at least one \s-1JIRA\s0 issue. You can make the reference optional by passing a false value to this option. .IP "valid => [01]" 4 .IX Item "valid => [01]" By default, every issue referenced must be valid, i.e., it must exist on the \s-1JIRA\s0 server. You can relax this requirement by passing a false value to this option. (Why would you want to do that, though?) .IP "unresolved => [01]" 4 .IX Item "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. .IP "by_assignee => [01]" 4 .IX Item "by_assignee => [01]" By default, the committer can reference any valid \s-1JIRA\s0 issue. Passing a true value to this option you require that the committer can only reference issues to which she is the current assignee. .IP "check_one => CODE-REF" 4 .IX Item "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: .RS 4 .IP "the \s-1JIRA::REST\s0 object used to talk to the \s-1JIRA\s0 server." 4 .IX Item "the JIRA::REST object used to talk to the JIRA server." Note that up to version 1.26 of SVN::Hooks::CheckJira this used to be a JIRA::Client object, which uses \s-1JIRA\s0's \s-1SOAP API\s0 which was deprecated on \s-1JIRA 6.0\s0 and won't be available anymore on \s-1JIRA 7.0.\s0 .Sp If you have code relying on the JIRA::Client module you're advised to rewrite it using the \s-1JIRA::REST\s0 module. As a stopgap measure you can disregard the \s-1JIRA::REST\s0 object and create your own JIRA::Client object. For this you only need the three arguments you've passed to the \&\s-1CHECK_JIRA_CONFIG\s0 directive. .IP "the hash representing the issue." 4 .IX Item "the hash representing the issue." .PD 0 .IP "the SVN::Look object used to grok information about the commit." 4 .IX Item "the SVN::Look object used to grok information about the commit." .RE .RS 4 .PD .Sp The subroutine must simply return with no value to indicate success and must die to indicate failure. .Sp Plese, read the \s-1JIRA::REST\s0 and SVN::Look modules documentation to understand how to use these objects. .RE .IP "check_all => CODE-REF" 4 .IX Item "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 \s-1JIRA::REST\s0 object used to talk to the \s-1JIRA\s0 server. The following arguments are references to hashes representing 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. .IP "check_all_svnlook => CODE-REF" 4 .IX Item "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. .IP "post_action => CODE-REF" 4 .IX Item "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 \&\s-1JIRA::REST\s0 object used to talk to the \s-1JIRA\s0 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 \&\s-1JIRA\s0 keys mentioned in the commit log message. The value returned by the routine, if any, is ignored. .IP "exclude => \s-1REGEXP\s0" 4 .IX Item "exclude => REGEXP" Normally you specify a \s-1CHECK_JIRA\s0 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 \&\s-1CHECK_JIRA\s0 directive. You can use this option to specify these exclusions by means of another regex. .PP You can set defaults for these options using a \s-1CHECK_JIRA\s0 directive with the string \f(CW\*(Aqdefault\*(Aq\fR as a first argument, instead of a qr/Regexp/. .PP .Vb 5 \& # Set some defaults \& CHECK_JIRA(default => { \& projects => \*(AqCDS,TST\*(Aq, \& 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 => \e&is_scheduled, \& }); .Ve .PP Note that you need to call \s-1CHECK_JIRA\s0 at least once with a qr/Regexp/ in order to trigger the checks. A call for (\f(CW\*(Aqdefault\*(Aq\fR doesn't count. If you want to change defaults and force checks for every commit, do this: .PP .Vb 2 \& CHECK_JIRA(default => {projects => \*(AqCDS\*(Aq}); \& CHECK_JIRA(qr/./); .Ve .PP The \f(CW\*(Aqpost_action\*(Aq\fR pseudo-check can be used to interact with the \&\s-1JIRA\s0 server after a successful commit. For instance, you may want to add a comment to each referred issue like this: .PP .Vb 5 \& # 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 referred 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/\e{(\ew+)\e}/"\e$svnlook\->$1()"/eeg; \& for my $key (@keys) { \& $jira\->POST("/issue/$key/comment", undef, { body => $format }); \& } \& } \& } \& \& CHECK_JIRA(qr/./ => { \& post_action => add_comment("Subversion Commit r{rev} by {author} on {date}\en{log_msg}") \& }); .Ve .PP You can use a generic \s-1CHECK_JIRA\s0 excluding specific directories from it using the \*(L"exclude\*(R" option like this: .PP .Vb 4 \& CHECK_JIRA(qr:^(trunk|branches/[^/]): => { \& exclude => qr:/documentation/:, \& # other options... \& }); .Ve .SS "\s-1CHECK_JIRA_DISABLE\s0" .IX Subsection "CHECK_JIRA_DISABLE" This directive globally disables all \s-1CHECK_JIRA\s0 directives. It's useful, for instance, when your \s-1JIRA\s0 server must be taken down for maintenance and you don't want to reject Subversion commits in this period. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\s-1JIRA::REST\s0 .IP "\(bu" 4 JIRA::Client .IP "\(bu" 4 \&\s-1JIRA SOAP API\s0 deprecation notice .SH "AUTHOR" .IX Header "AUTHOR" Gustavo L. de M. Chaves .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by CPqD . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.