[asterisk-dev] JIRA, Commit Messages, and Smart Commits (oh my)

[Matthew Jordan]

On Tue, Mar 18, 2014 at 1:25 PM, Matthew Jordan <mjordan at digium.com> wrote:
> Hey everyone -
>
> Due to a security vulnerability in JIRA, we recently had to upgrade
> JIRA to version 6.2. While this was a good thing (tm), it did break
> the snot out of the Subversion plugin. That plugin does a number of
> things; one of those things is auto-closing issues based on the commit
> message.
>
> Traditionally, the plugin used the following nomenclature to close an issue:
>
> (closes issue JIRA_ISSUE)
>
> Likewise, tagging a commit with the following linked the commit
> message to the issue:
>
> (issue JIRA_ISSUE)
>
> While I'd like to believe the Subversion plugin will get fixed at some
> point, our initial forays into getting it fixed haven't been fruitful.
> Part of this is reticence on our part to 'customize' the plugin or our
> JIRA instance further (more on that in a bit); another large part is
> Atlassian appears to be focussing on an alternate method for tying
> commit messages back to issues (more on that in a bit as well). Long
> story short, it doesn't appear like anyone is in a hurry to fix the
> old Subversion plugin.
>
> Question: why not hack on the Subversion plugin and/or JIRA?
>
> Answer: we could hack around on the Subversion plugin and/or JIRA (it
> isn't clear yet who is at fault), but the more customization we put
> into it the harder it is to upgrade the project's JIRA instance. This
> makes it harder to respond quickly to security vulnerabilities. We've
> done a lot of work over the past year or so minimizing the
> customizations so that we can respond quickly to said vulnerabilities
> in JIRA, and it's been very handy. Unless there's a giant outcry
> against what I'm about to propose, I'd hope that we don't have to try
> and modify the plugin ourselves.
>
> Question: what is this alternate method that Atlassian has?
>
> Answer: Atlassian Smart Commits [1].
>
> Since we have Fisheye [2] integration with JIRA, we can use a
> different commit message format that will trigger the smart commits in
> Fisheye, which will do all of the auto-closing for us in JIRA. In
> fact, as the name 'smart commit' implies, it can do a lot more than
> just close the issue, including leaving comments and other fanciness.
> It does mean however that our commit message format will have to
> change.
>
> The biggest implication of changing the commit message format is
> making sure that patch submitters are properly attributed, such that
> the release summary scripts and other parts of the Asterisk project
> pick up who actually wrote the patch. Right now, I'm proposing
> something like the following:
>
> ASTERISK-12345 #close
> ASTERISK-12345 #comment patch my_awesome_fix.diff submitted by jdoe
> (license 12345)
>
> You can see a commit that contains some smart commit tags in it here
> [3], which use a format similar to what is above.
>
> What do you all think?
>
> Matt
>
> [1] https://confluence.atlassian.com/display/AOD/Processing+JIRA+issues+with+commit+messages
> [2] https://code.asterisk.org/code/
> [3] http://lists.digium.com/pipermail/asterisk-commits/2014-March/067893.html
>

Update!

This didn't work as well as I'd hoped.

As Walter pointed out on https://reviewboard.asterisk.org/r/3554/,
there's a few problems with this approach. Every time a commit is
merged - which can happen a lot - the commit message is processed
again by FishEye/JIRA. This results in a few problems:
(1) The #close causes a the issue to be re-closed. Committers get
spammed with some angry messages from JIRA about how you can't close
an already closed issue.
(2) The #comment results in multiple comments being left. Even if that
weren't the case, having #comment note who uploaded the patch or who
reported the issue is somewhat useless on the issue itself - since
that information is already on there.

Walter's patch is still useful - if the commit message can be
'massaged' between merges, that will certainly result in less
processing by FishEye/JIRA and less spam messages. There's a few other
things that could also help this:

(1) We *should* be able to convince JIRA that closing an already
closed issue is okay. I'll take a look at doing that this week.
(2) The #comment approach should probably be abandoned. As it turns
out, the various scripts can process the original nomenclature just
fine, so long as they are preceded by the #close smart commit:

ASTERISK-12345 #close
Reported by: Matt Jordan
patches:
  my_awesome_fix.diff submitted by jdoe (License 12345)


Thoughts?

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org