Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SVN::Hooks::CheckJira(User Contributed Perl DocumentatSVN::Hooks::CheckJira(3)

NAME
       SVN::Hooks::CheckJira - Integrate Subversion with the JIRA ticketing
       system.

VERSION
       version 1.34

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 without 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 committer 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 committer can reference any valid JIRA issue.
	   Passing a true value	to this	option you require that	the committer
	   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::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 JIRA's SOAP API which
	       was deprecated on JIRA 6.0 and won't be available anymore on
	       JIRA 7.0.

	       If you have code	relying	on the JIRA::Client module you're
	       advised to rewrite it using the JIRA::REST module. As a stopgap
	       measure you can disregard the JIRA::REST	object and create your
	       own JIRA::Client	object.	For this you only need the three
	       arguments you've	passed to the CHECK_JIRA_CONFIG	directive.

	   the hash 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::REST 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::REST object
	   used	to talk	to the JIRA 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.

       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::REST 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 referred	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 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/\{(\w+)\}/"\$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}\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.

SEE ALSO
       o   JIRA::REST

       o   JIRA::Client

       o   JIRA	SOAP API deprecation notice
	   <https://developer.atlassian.com/display/JIRADEV/SOAP+and+XML-
	   RPC+API+Deprecated+in+JIRA+6.0>

AUTHOR
       Gustavo L. de M.	Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by CPqD <www.cpqd.com.br>.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2016-11-10	      SVN::Hooks::CheckJira(3)

NAME | VERSION | DESCRIPTION | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SVN::Hooks::CheckJira&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help