Changes between Version 29 and Version 30 of WorkingConventions/Git


Ignore:
Timestamp:
Aug 14, 2013 7:36:09 AM (2 years ago)
Author:
hvr
Comment:

Extend Git commit message section

Legend:

Unmodified
Added
Removed
Modified
  • WorkingConventions/Git

    v29 v30  
    3636== Commit messages ==
    3737
    38 We have a simple convention for commit log messages:
     38Please try to follow the general convention for the [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Git commit message structure] as many Git tools rely on this. Moreover, take into account that the commit message text is interpreted as WikiFormatting in Trac.
    3939
    40    * If your patch fixes breakage in the build, then begin the patch name with `"FIX BUILD"`. e.g.
     40For GHC, we have a simple convention for commit log messages:
     41
     42 * If your patch fixes breakage in the build, then begin the patch name with `"FIX BUILD"`. e.g.
    4143{{{
    4244  FIX BUILD Use the right find on Windows systems; fixes bindist creation
    4345}}}
    44    * If your patch fixes a bug, then include the ticket number in the form `#NNNN` in the patch name, e.g.
     46 * If your patch fixes a bug, then include the ticket number in the form "''<verb>'' `#NNNN`" in the commit message, e.g.
    4547{{{
    4648  withMVar family have a bug (fixes #767)
    4749}}}
    48      '''Git will then add a link to the commit from the ticket''', so that people watching the ticket can see that a fix has been committed, and in the future we can easily find the patch that fixed the ticket.  When navigating the git history on Trac, you will also be able to jump directly to the ticket from the commit.
     50 '''''Git will then add a link to the commit from the ticket''''' (as soon as the commit becomes reachable from the `master` HEAD), so that people watching the ticket can see that a fix has been committed, and in the future we can easily find the patch that fixed the ticket.  When navigating the Git history on Trac, you will also be able to jump directly to the ticket from the commit.
     51
     52 '''Ticket Referencing Syntax in More Detail'''
     53
     54 As stated above, the basic syntax for referencing tickets from commit messages is of the form "''<verb>'' ''<ticket-ref>''".
     55
     56 An example for ''<ticket-ref>'' is "`#1234`" or "`#1234 and #1235`", where the latter simply references two tickets at once for convenience.
     57
     58 The currently recognized verbs for merely adding a comment to a Trac ticket are
     59{{{
     60addressing address re references refs see Trac
     61}}}
     62 (N.B.: Currently, you ''need'' to put a verb in front of the ticket reference in order for the reference to be recognized; this is different from GitHub)
     63
     64 Whereas the verbs recognized for adding a comment *and* closing the ticket are
     65{{{
     66close closed closes fix fixed fixes resolve resolves resolved
     67}}}
     68 (N.B. this is the same as [https://help.github.com/articles/closing-issues-via-commit-messages GitHub's issue close syntax])
     69
     70 The ticket referencing syntax is designed in such a way that you can embed ticket references in English sentences. For instance, the following fairly complicated example of what you can do is with a commit message of:
     71{{{
     72Changes blah and foo to do this or that
     73
     74Fixes #10 and #12, and refs #13.
     75}}}
     76 This will close #10 and #12, and add a comment to #10, #12, and #13.
     77
     78 Please note, that these verbs are only scanned for in the Git repositories associated with this Trac instance (see [source: Source Browser]). It is planned to introduce additional verbs for moving a ticket into the '''merge''' ticket state instead of straight to the '''closed''' state.
    4979
    5080== Line endings ==