New Git-commit-message -> Trac-ticket interaction (was: NOTICE: Gitolite migration is complete.)

[Herbert Valerio Riedel]

On 2013-08-10 at 11:06:06 +0200, Herbert Valerio Riedel wrote:
> And finally, the changes resulting from the new Trac commit-hook
> integration is worth a separate posting of its own to follow shortly.

The new post-receive hook for notifying Trac about new commits has been
updated to use Trac's CommitTicketUpdater[1]

One of the changes is the way commit messages are added to a ticket
comment:

 - Previously, the commit message was put into a verbatim code block, as in
   http://ghc.haskell.org/trac/ghc/ticket/8121#comment:2

 - Now, the commit message is wrapped in a code block using Trac's
   CommitTicketReference wiki processor which effectively interprets the
   commit message as Trac wiki markup[2]. This is more consistent with the
   way commit messages are exposed in other places throughout Trac and
   allows for proper Wiki and URL links in the ticket comment view.

   For instance, http://ghc.haskell.org/trac/ghc/ticket/8121#comment:3


As for *when* a Git commit is actually associated with a ticket:

 - Currently, only the 4 Git repos associated with GHC Trac
   (ghc,nofib,testuite,base; [3]) are scanned for ticket
   references.

 - Currently, only if a commit becomes reachable during a "git push"
   from the 'master' branch it gets scanned for trigger words. This is
   the simplest way to avoid duplicate commit messages getting added as
   comments to tickets (and avoid premature ticket closing).[4]

 - The ticket-referencing syntax explained below must be used, for the
   ticket reference to get recognized.


To quote the documentation[1]:

,----
| The basic syntax is of the form [command] [ticketreference]. A colon
| between the command and the ticket reference is allowed. The
| ticketreference also allows to list multiple ticket numbers separated by
| spaces and/or comma. The word 'and' is also allowed between ticket
| numbers.
| 
| You can optionally refer to tickets with the following words
| 
| ticket, issue, bug
| Examples (note: not verified!):
| 
| close #10
| closed: #10
| closes ticket #10
| closes ticket:10
| fixes #10
| fixes bug: #10
| see issue #5
| references #5, #6
| fixes bug #10 and #11
|
| A fairly complicated example of what you can do is with a commit
| message of:
|
| Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12.
|
| This will close #10 and #12, and add a note to #12.
`----

The command verbs currently recognized for referencing a ticket are
currently:

| addressing addresses re references refs see Trac

...and the verbs currently recognized for referencing *and* closing a
ticket are

| close closed closes fix fixed fixes

Consequently, if you just write "Fixes Trac #1234" in your commit (which
occurs quite often in the git history), this will only reference the
ticket but *not* close the ticket.

If closing from commits is not desired or causes problems, we can move
the close/fix verbs into the "reference-only" set of verbs and be done
with it.

If there's something you'd like to behave differently, please tell us.
If accomplishable with reasonable effort, we're happy to implement it.


The information from this posting may/should/shall/will be put on the
GHC Trac Wiki as well for future reference.

Cheers,
  hvr

 [1]: http://trac.edgewall.org/wiki/CommitTicketUpdater
 [2]: http://ghc.haskell.org/trac/ghc/wiki/WikiFormatting
 [3]: http://ghc.haskell.org/trac/ghc/browser
 [4]: Should the need arise, we can consider a more sophisticated
      approach can be used, which would consider commits in more than
      just the 'master' branch.