Changes between Initial Version and Version 1 of Development/CommitConventions


Ignore:
Timestamp:
08/09/09 11:15:15 (10 years ago)
Author:
ibboard
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Development/CommitConventions

    v1 v1  
     1[[PageOutline(2-5)]]
     2= Commit Conventions =
     3
     4The following are notes on the WarFoundry conventions for committing to source control. They should, in general, be quite similar to other systems using Subversion and Trac to integrate tickets with source control.
     5
     6== Code quality on commit ==
     7
     8There are three priorities when committing code:
     9 1. the code compiles
     10 1. the code works
     11 1. the commit is as small as possible
     12
     13=== Code must compile ===
     14All code commits '''must''' comply with the first rule unless completely unavoidable and must compile. Ideally someone should be able to check out any revision and build it, so the code must compile. The other advantage of making sure that code compiles is that it stops the situation occurring where a second commit isn't made for a while (due to network issues or time constraints) that would have allowed the code to compile, ensuring that everyone can update without fear of things breaking
     15
     16=== Code should work ===
     17Code commits should also commit working code. This isn't essential, as there are situations where a feature may compile but its functionality isn't complete. If it isn't complete (or if, for example, a listener hasn't been attached to a button) then there should be a ticket open to track the work being done.
     18
     19=== Commits should be small ===
     20The final requirement is not essential but is very useful when possible as it allows change tracking to be made at a more granular level. It also reduces the amount of work you might have to do to rebuild your changes if you do something wrong as you have a more recent point to go back to.
     21
     22Committing little and often is easier and more useful than doing a big commit.
     23
     24== Commit Messages ==
     25
     26As part of the integration between Subversion and Trac to link bug reports/tickets to source code changes, we have a couple of fairly standard hooks on the repository. For information on conventions when referencing tickets and revisions, please read the [wiki:TracConventions Trac Conventions] page.
     27
     28=== Format ===
     29
     30The format for a commit message is up to the individual, but a convention that seems to work well in a corporate environment that should transfer well is to use something like:
     31{{{
     32Re #3: Ticket title (or brief description similar to the title)
     33 * Some grouping of changes
     34 * Some other group of changes
     35 * Another group of changes
     36}}}
     37
     38This format works well in both Subversion and Trac (which would munge everything on to a single line without the bullets) and using a descriptive overview of changes rather than the detail means the commit message abstracts away the detail. If someone wants to know exactly what is involved in the commit that "Added LGPL headers to all files" then they can look at the revision details and the file differences.
     39
     40=== Pre-commit hook ===
     41
     42When you try to commit code, but before the code is actually committed, the system checks your commit message for Trac ticket references (e.g. #1 or ticket:2). You '''must''' reference at least one ticket in all commit messages or the commit will be rejected.
     43
     44This is generally a good thing as all code should normally be written because of a ticket. If there isn't a ticket for the feature or the bug then why is the code being written? There are, however, times when you've closed a ticket and found a bit of code that wasn't checked in (e.g. [ticket:1#comment:11 here]), or when a very short fix needs to be made where a ticket is more effort than the fix. In these situation you should reference the closed ticket (if applicable) and use the keyword "no-open-ticket" (with the hyphens). Excessive and unnecessary use of the keyword should be avoided.
     45
     46=== Post-commit hook ===
     47
     48So that you don't have to update Trac manually, we also have links from the commit message to referenced Trac tickets. These let you tie commits to a ticket, leave comments on the ticket and close the ticket without accessing Trac directly and copying what you just sent to Subversion.
     49
     50==== Adding comments to a ticket ====
     51
     52References to tickets using any of "references", "refs", "addresses", "re" or "see" followed by a [wiki:WikiFormatting#TracLinks Trac ticket link] (e.g. #1 or ticket:2) leaves the referenced ticket in its current state and [ticket:1#comment:3 appends the commit message].
     53
     54There are no hard and fast rules, but in general "re #ticket" is generally sufficient.
     55
     56==== Closing a ticket ====
     57
     58If the commit resolves the issue a ticket refers to then the ticket can be closed with the commit message. This is done in a similar manner to commenting on a ticket by using "close", "closed", "closes", "fix", "fixed" or "fixes" followed by a [wiki:WikiFormatting#TracLinks Trac ticket link] (e.g. #1 or ticket:2). This will [ticket:1#comment:10 add the comment to the ticket and close it].
     59
     60There are no hard and fast rules for which word to use when closing tickets, but there are some rough guidelines that may make sense. "Fixes" seems to be the most appropriate keyword to close bugs/defects since they are broken bits of functionality. Tasks and enhancements seem more like types of tickets that get "Closes" since they're not broken, they're just an issue that needs resolving.
     61
     62==== Handling multiple tickets ====
     63
     64In general commits should be made against a small number of tickets, but [http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook#L68 multiple tickets can be updated] with a single commit message through lists and the word "and".