wiki:commitmessages

Subversion commit messages

In attempt to get consistent and useful commit messages in the subversion repository, this page describes a number of guidelines for writing commit messages. Please make sure all commit messages follow these guidelines.

General guidelines

  • Commit messages are intended to make the history of certain components easily visible. By reading the commit message, someone should know what changed, what the (side-)effects of the change are and why the change was made.
  • A commit message should be useful on itself, even without looking at the actual diff of the commit (in fact, the commit message is often used in deciding whether or not to look at the diff, when looking for the cause of a specific bug or behaviour).
  • A commit should contain a single, logical change. Unrelated changes should be in separate commits. Changes that are related to the same subject, but not interdependent should also go into separate commits if possible.
  • A commit message should primarily describe what was changed. The level of detail of this description is a bit subjective, and often depends on the scope of the change.
  • A commit should describe the (user-visible) effects of the change, if appropriate. This is especially relevant for side-effects that are not obvious from the change itself.
  • Unless it is obvious, a commit message should include the rationale for the change.
  • If a commit imports a change or package from OpenWRT, it should say so. Include the relevant OpenWRT revision number and note any extra changes made.
  • If a patch, or other significant contribution was provided, don't forget to include a relevant credit in the commit message.

Message format

The actual format of the message is as follows:

component: Summary of changes

Longer description, possible multiple paragraphs.

Closes: #123
References: #124, #125 and #126

The component prefix is used to note the package or component concerned in the change. This should just be a single word, like "umtsd" or "buildsystem". It helps to look at the svn log for the directory you're working in to keep things consistent with previous commit messages. This prefix can be left out if no relevant component or package applies (for very general changes, for example).

The summary of changes should focus on what has changed. It shouldn't be overly long, try to keep the complete line within 80 characters, if possible (but let it extend past the 80 character if needed, don't wrap the first line). Make sure this is a single sentence, complete with capitalization (but omit a trailing stop).

The longer description should contain all of the other info, such as detailed effects and rationale. This description should be wrapped around 70-80 characters and also consist of complete sentences (including trailing stops). Multiple paragraphs are separated by blank lines.

Finally, you should reference relevant tickets in the format shown above. Use the Closes command on the commit that actually resolves a ticket and use References on other related tickets (guideline: does the ticket help in understanding the changes made in the commit?).

Examples

    umtsd: Remove usb_hotplug
    
    This utility has been replaced by a hotplug script shipped with the
    usb_modeswitch package now.
    
    References: #865

This message is good, since it clearly describes what has changed and why this change was needed. It provides a link to the relevant ticket as well. It could be slightly improved by explicitly stating that there should be no visible effects of this change.

    fuse: Update to 2.8.4
    
    This imports the fuse package from OpenWRT trunk (r22919) unmodified.
    
    Note that this also switches to the in-kernel fuse module, since fuse
    2.8.x no longer includes a kernel module. Before, the in-kernel module
    was only used for kernels >= 2.6.25, though it is included for kernels
    >= 2.6.14). This might cause an older version of the kernel module to be
    used by this upgrade.

    References: #490

This message is good, since it clearly describes what has changed, including relevant version and revision numbers. It also mentions a potential side-effect that is unexpected from the change itself. It could be slightly improved by including the rationale for the change (but perhaps that's also clarified by the ticket referenced).

    transmission: Update to 2.04
    
     * Update the crypt patch to apply to 2.04.
     * Move the -lcrypt additions in the crypt patch to more logical places.
     * Remove the memory_footprint patch, this has been applied upstream.
     * Depend on libevent, since that is no longer bundled with transmission.
     * Update the mk_fon_img.sh script to get the new version and include libevent.
    
    Note that this is not a verbatim copy from the Transmission 2.04 version from
    OpenWRT, since there were a bunch of changes we didn't need and our version of
    Transmission has also a bunch of changes (in the config file, init scripts,
    etc.).
    
    Based on a patch by Paolo Valleri.

    Closes: #564

This message is good, since it contains a complete list of the changes required to get the new version of Transmission working. It also explicitly notes why the OpenWRT version could not be used. This commit could perhaps been improved by splitting it into multiple commits (it's quite a big change), but that might not be practical. Verbosely documenting the separate sub-changes should help a lot in understanding them.

    Make advertisement timeout shorter

This message is bad, since it is entirely unclear. What timeout is concerned here, and why does it need to be shortened?

    Lots of umts fixes

This message is bad, since it does not provide any details about the changes made or the bugs fixed. The commit it describes is also too big: It contains a number of unrelated changes (translations, packaging, actual code), making it harder to find out why something was changed later on.

Last modified 4 years ago Last modified on Sep 18, 2013, 1:15:43 PM