SVN::H...eckJira(3pm)

📦
version 1.36 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💅 SVN::H...eckJira — the perl doc page, but make it make sense

okay bestie, sit down, hydrate, because this one's a Subversion + JIRA crossover episode and it's lowkey iconic. this is part of the User Contributed Perl Documentation family, and the whole thing is version 1.36. no cap.

✨ NAME ✨

SVN::Hooks::CheckJira — the plugin that makes Subversion and the JIRA ticketing system hold hands. 🫶

🌸 VERSION 🌸

version 1.36</purl>

version 1.36

🦋 DESCRIPTION 🦋

so here's the vibe: this SVN::Hooks plugin is a gatekeeper. it says that any Subversion commit touching some parts of the repo structure must reference valid JIRA issues in the commit log message. it's giving "no ticket, no entry" 💅

and how do you spot a JIRA issue? by its key. a key = a sequence of uppercase letters, then a hyphen, then a sequence of digits. like: CDS-123, RT-1, and SVN-97. periodt.

it's active in the pre-commit and/or the post-commit hook. yes, both. she's flexible.

and she's configured by the following directives 👇

🎀 CHECK_JIRA_CONFIG(BASEURL, LOGIN, PASSWORD [, REGEXP [, REGEXP]]) 🎀

this directive is literally just "how do we log into JIRA".

  • 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 get referenced in the commit logs. (yes, they need to actually be able to see the projects. permission check first, bestie.)

the fourth argument is an optional qr/Regexp/ object. it gets matched against the commit logs to pull out the list of JIRA issue keys. by default, JIRA keys are looked for in the whole commit log, which is equivalent to qr/(.*)/. sometimes that's suboptimal though 😭 because a user can drop text in the message that inadvertently looks like a JIRA issue key when it sooooo isn't one. with this argument, the log message is matched against the REGEXP, and only the first matched group — aka the part captured by the first parenthesis ($1) — is used to go looking for JIRA issue keys.

the fifth argument is another optional qr/Regexp/ object. this one matches JIRA project keys, which match qr/[A-Z]{2,}/ by default. but 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 it here too. slay.

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 you 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 get checked against their current status on JIRA, according to the options specified after the REGEXP.

here are the available options, bestie, all of them, no skipping 💖

🌈 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 handing this option a comma-separated list of project keys.

🌈 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? 🙈 genuinely asking.)

🌈 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. pass a true value to this option and now the committer can only reference issues to which she is the current assignee. main character energy, but for tickets. 👑

🌈 check_one => CODE-REF

if all the checks above still 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:

  1. 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.
  2. the hash representing the issue.
  3. 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.

please, read the JIRA::REST and SVN::Look modules documentation to understand how to use these objects.

🌈 check_all => CODE-REF

sometimes checking each issue separately isn't enough. you may want to check some relation among all the referenced issues. in that 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, bestie — it's 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/. like so:

# 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,
});
⚠️ okay so this bit matters: 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. she's the "brb going offline" button. 💜

💖 SEE ALSO 💖

🍓 AUTHOR 🍓

Gustavo L. de M. Chaves <gnustavo@cpan.org> — the actual genius behind this. give them their flowers 💐

This software is copyright (c) 2022 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.

and that's the whole page, bestie!! 🌈 this beauty was rendered by perl v5.36.0 and stamped 2022-09-11, straight from the User Contributed Perl Documentation squad. go forth and make your commit logs JIRA-compliant, no cap, ily 🫶✨💅

📦 where this page comes from