Navigation: (IDEACommit)

The premises on which these guidelines have been established:

  1. Commits are a very important channel of communication between developers and thus, clarity of commits is as important as sending a readable email message.
  2. Commits provide historical information and set context for new developers to comprehend transformations to the code base.
  3. Under rare circumstances commits need to be rolled-back. It is imperative that this process is made painless. Trying to extract partial changes from each commit is extremely painful and costly. We are aiming to establish a agile process of software developement and one critical aspect of that is ability to quickly roll back inappropriate changes.

A good way to think about this is in terms of 'time cost', i.e.,

  1. Cost of comprehension: How much will it cost for another developer to understand what your changes are about
  2. Cost of rollback: How much will it take to roll back and what is the cost of the roll back itself

The essence is to try and keep both the costs down and that means taking somewhat additional care when we commit something.

Commit Guidelines

There are three aspects to our guidelines:

  1. What to commit
  2. When to commit
  3. How to commit

What to commit

Commit related changes together. The idea behind related is a discrete unit that can be rolled back and from an application semantic perspective does not break (as far as possible) or affect another functionality. For example, trying to roll back changes associated with one feature checked in as one commit with another feature will require the developer to semantically separate the two out to be able to add the changes related to second feature back in again, a very costly process.

Types of good commits:

  1. Changes to files all related to a single ticket being worked on. This ticket can be a defect, enhancement or task
  2. Formatting changes to a bunch of files. This might not be associated with a ticket.

Examples of good commit messages:

  1. r6432
  2. r6388
  3. r6384 (Link to earlier commit changeset)
  4. r6383
  5. r6373 (Formatting fixes)
  6. r6438 (closing ticket)
  7. r5662 (addressing multiple tickets)

Type of bad commits:

  1. Changes to files related to two semantically unrelated tickets (more on this later) going in the same commit
  2. Lots of formatting changes and ticket related changes together

Examples of bad commits:

  1. r2966
  2. r2740
  3. r6099 (please see the roll-back also r6100)
  4. r5860

As usual there are some grey areas. Following are acceptable:

  1. Changes related to two tickets because of the same underlying problem. In this case, please make sure all the affected ticket numbers are in the commit message
  2. Small set of formatting fixes in the general vicinity of the ticket related changes.

When to commit

Here is a check list of tasks to ensure that your commit will go smoothly:

  1. Make sure the entire system can build and all test cases pass.
  2. Check and make sure your new code conforms to our coding conventions.
  3. Check and make sure you have the correct copyright on all the files being added
  4. If you are adding new external dependencies, please make sure that the copyright license conforms with the spirit of the Apache license we use. Please check if you are not sure.
  5. Please make sure you have added test cases (specially for fixed bugs)
  6. Spend a few minutes composing your commit message. Please treat this with the same seriousness as an email message to another individual
  7. Use your local set of tools to determine what exactly is being committed. For example svn diff etc.
  8. After committing take a couple minutes to go to Timeline and check if what you see there is correct.

How to commit

The commit message is the key here in communicating to other developers. Please note that this commit message is visible via multiple channels:

  • Email message to committers (please see commit emails)
  • Any developer looking at source code revision logs (example svn log -r 5594)
  • Trac timeline (Timeline)
  • Ticket history (example #910)

Thus your commit message has to take both the audience and the channel they are reading the commit message into account. A good template to follow is as follows: 

<one line summary of change>

<paragraphs outlining details>

<trac commands listing actions this change set has on tickets>

Some examples: 

Fixed duplicate author entries in feed results.

In AmbraFeedResult.java an additional author was being added to the default
feed result. This resulted in 2 <author>AUTHORNAME</authorname> elements
for each read entity. Fix by removing the extra author addition for
non-extended feed case.

This addresses #1082.

Rolling back r7053.

This is because:
 * Invalid trac command to link to the correct ticket. There is no 'Ref'
   command. 
 * log.debug(description) will provide absolutely no useful information in the
   log file to provide any understanding. Please look at other log messages to
   see how to make this useful. 

Added social bookmarks to article pages.

This is a recommit to r7049 with fixes to code formatting. The main fix adds
social bookmarks to article pages. This change is already in production and
is actually only now being checked into subversion to bring the two into sync.
The change set replaces the article content freemarker template and provides
corresponding changes to the associated CSS to display the same.

This change can be improved upon and I have created tickets, re #1079 & #1080
& #1081 to address the same.

This change set in itself addresses #1075.
  1. The first line should be a brief summary of what the commit is about. The first line typically will go into the header of the email message and allows an audience to quickly ascertain whether they want to read the commit and changes in detail. For example, formatting changes first line can just be 'Formatting Changes.' with rest of the commit message describing what the formatting changes are. If a change is being rolled back it should say the change set being rolled back here.
  2. The message should then outline the changes in detail and why. This should allow other developers to look and understand the context of your changes and if necessary ask questions to further their understanding or help in improve the design of the change.
  3. It is very important that the ticket numbers are addressed towards the end via Trac wiki formatting rules. For example tickets numbers should start with '#' and changeset with 'r' etc. This creates Trac subversion plugin to create links from tickets to changesets and vice versa. This allows perusing in Trac very useful. Please see next section for Wiki syntax details.
    1. A commit that closes a ticket(s) should say 'Fixes #<ticket number>' (all tickets) in the commit message
    2. A commit message that partially addresses a ticket or tickets should say 'Addresses #<ticket number>' for all tickets it addresses
    3. A commit that fixes some tickets and addresses other should have both 'Fixes #<ticket number' for tickets that need to be closed and 'Addresses #<ticket number>' for other tickets that the commit partially addresses.

Wiki Syntax

Trac will recognize and format any wiki syntax in commit messages when you view them in trac. This is very useful (see for example [83]). But, since the messages can also be view via normal subversion commands, this feature should not be overused. Luckily the wiki markup often does not reduce the readability of the unformatted message. But here are some suggestions:

  • Do use: lists (*, 1.), blockquotes, preformatted text ({{{ }}}), trac-links (tickets (#N), changesets ([N]))
  • Don't use: tables, processors, macros

Closing/Commenting-on Tickets

You can automatically comment on or close one or more tickets by including special "commands" in the commit message. These can be anywhere, as the whole commit message is searched. The message is searched for strings of the form:

  • command #1
  • command #1, #2
  • command #1 & #2
  • command #1 and #2

where 'command' is one of "close", "closes", "closed", "fix", "fixes", "fixed", "addresses", "re", "refs", "references", or "see", and N in #N is the ticket number. All of these cause the commit message to be added as a note to the tickets; additionally the close* and fix* commands cause the corresponding tickets to be closed.

Note that you can both fix and reference as many tickets as desired in the commit message.