Writing Commit Messages

Using a uniform way of writing commit messages makes the commit log much more readable. And much better searchable if one is interested in certain types of commits. Therefore some general guidelines for committing are established. Of course it's up to a project to decide for itself whether or not to follow these guidelines.

Apart from these guidelines there are a few handy keywords that you can use in your commit messages. These keywords together with an issue number either close that issue or link the commit to it. Linked commits are shown in an issue's detailed view.

Standardized commit messages

These guidelines are distilled from the way the OpenTTD devs describe their commits to the OpenTTD repo.

Each commit, you should start with a keyword describing the type of commit you're making. This keyword is followed by a colon, a space and a short but descriptive description of what the commit is about. Right below you'll find a list of common standard keywords along with a description on when to use them.

  • Feature: whenever you add something new to the repo which changes the compiled result of the set. In case of NewGRF usually accompanied by new NFO code.
  • Add: whenever you add something new that doesn't change the compiled result. For instance when you add new graphic files but no NFO code to put 'em in the set.
  • Fix: whenever you fixed something that was broken (see also #Linking to Revisions).
  • Change: whenever you change the internal structure of the repo.

Some less used keywords:

  • Codechange: whenever you change the internal structure of the code. Generally without adding new functionality.
  • Update: whenever you update something that doesn't fit other keywords. If in doubt, it's usually a feature.
  • Cleanup: whenever you removed something that became obsolete.
  • Doc: whenever you did something with the set's documentation.
  • Merge: whenever you committed something without merging first and need to do an extra merge to re-incorporate previous changes (see also #Linking to Revisions).
  • Revert: whenever you reverted something already pushed (if you didn't push yet, hg rollback instead).

See also http://wiki.openttd.org/Commit_style for a consistent way to write commit messages.

Linking to revisions

In some cases you fix something that got broken in a certain revision. In that case it's useful to include the revision hash or revision number of when it got broken in the commit of the fix:

  • Fix (commit:XXXXXXXXXXXX): In this case XXXXXXXXXXXX refers to the hexadecimal revision hash of the revision that broke whatever you're fixing.
  • Fix (rXX): In this case XX refers to the decimal revision number of the revision that broke whatever you're fixing.
Something similar applies to merge:
  • Merge (commit:XXXXXXXXXXXX, commit:YYYYYYYYYYYY)
  • Merge (rXX, rYY)

Linking to and closing issues

If you use certain keywords in combination with an issue number (not to be mistaken by revision number!) Redmine will recognise those and automagically link the commit to the issue. Some keywords will even cause an issue to be closed automatically, saving you the trouble doing it manually. Feel free to combine these keywords with the standard commit keywords:

Add #234: Add new graphics for petrol stations
Feature #234: Implement drive-through petrol stations

The following keywords will also close the issue and set it's percentage to 100% done:

  • Bug #XX
  • Fix #XX
  • fixed #XX
  • fixes #XX
  • close #XX
  • closes #XX

Note: The OpenTTD style of referencing an issue like
Fix [FS#1342]: Remove PBS signals
does not work as Redmine does not support to referencing on [] (neither directly nor escaped), as such it'd either only reference everything or close everything when a number is given in that format.