HEADS UP! was: Re: New Git-commit-message -> Trac-ticket interaction

[Simon Marlow]

Just in case there are other people (like me) who didn't notice this, 
the syntax for telling git that you want to update a Trac ticket in the 
commit log has changed.  Read Herbet's message for details.

I used to just mention the ticket number in the commit message "blah 
blah (#1234)", the new syntax for this is "blah blah (see #1234)".

I have updated 
http://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git to mention 
this, but it could probably do with more complete docs since the 
standard Trac docs don't take into account our local settings.  Herbert, 
could you expand that please?

Cheers,
	Simon


On 10/08/13 10:57, Herbert Valerio Riedel wrote:
> 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.
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>