Commit messages - providing history and credit

As a module or theme maintainer or contributor, you may be making commits to the Drupal contributions CVS repository on a regular basis, both for your own code and changes contributed by others. Appropriate comments along with those commit messages are the key to providing context that others need to understand the development of your code.

Quick summary for the impatient

Use this syntax for commit messages:

Issue Categories provides an indication of whether it is a bug, feature, or task. Issue categories can be ommitted if you are phrasing summaries as explained in the following chapter.

Give details

Provide at least a short summary of what is contained in the commit. In most cases re-using the title of a related drupal.org issue is sufficient. If there is no meaningful issue title yet, try to summarize the change.

Usually, commit messages start with the (past tense) verb

• Added (new feature)
• Fixed (bug fix)
• Changed (task)
• Updated (task, especially used for required changes due to changes in 3rd party code)

Note that it might not be trivial to phrase a short summary that starts with one of those verbs sometimes - however, if used consequently and consistently, you will get used to it. Using those verbs makes it easier for users of your module to determine whether a new release contains only bug fixes or maybe also new features or other stuff that may require testing on an existing production site.

The following hint might help you in writing comprehensive summaries:

Try to keep the commit message to something like the title of the issue or a single sentence describing what was fixed. Do not to describe what was really wrong, just say what was fixed. If that makes sense.

Reference the drupal.org issue, if available

The common practice in the Drupal community is to create a project issue for every change in a module/project. If the change you are committing relates to an issue on drupal.org, give the issue number, preceded by a pound sign (#). This convention is interpreted by the CVS module on drupal.org to provide a link back to the issue in the publicly visible CVS log.

The message should start with the issue number. Do not use prefixes such as Patch.

Give credit

If others have contributed to the change you are committing, take the time to give them credit. Each commit message should contain at least one contributor name, even if it refers to your own username. Once a project has more than one maintainer, or is taken over by a new maintainer, it's very valuable to know who actually wrote or contributed a certain change.

To do this, append by [username]: to the issue number. Separate multiple contributors with commas. You should not credit yourself if you are just committing a patch that has been created by someone else.

If more people have contributed to a change, pick the major contributors and add et al:

If a change/commit does not relate to an issue for any reason, you should skip the issue number, but still give credit:

It is customary to use the usernames from drupal.org and not contributors' CVS account names since they may be different.

Re-use commit messages in CHANGELOG.txt

To help developers and users understand what has been changed recently, each project should include a CHANGELOG.txt. When following these guidelines, you can simply copy'n'paste a commit message from/to your changelog in front of committing a change. They are then able to look at all recent changes in CHANGELOG.txt - which then results in a comprehensive and clearly laid out overview of all commit messages. This is most important for users when upgrading from a previous version (examples: 1, 2, 3).

Moreover, you will get a great output for project release nodes when using the cvs-release-notes script (Example).

In short, by following these guidelines, you get a comprehensive CVS log, changelog entries for CHANGELOG.txt, and contents for release nodes for free.

Best practice:

1. Apply a patch.
2. Add a changelog entry to CHANGELOG.txt.

   Note: All lines in CHANGELOG.txt should wrap at 80 chars. If a changelog entry does not fit into 80 chars, subsequent lines belonging to the same entry should be indented by 2 spaces.

3. Copy the changelog entry and re-use it 1:1 for the CVS commit message (but remove linefeeds and indents of long lines).

Please note that you should update CHANGELOG.txt and insert a new release heading in front of creating a new release:

Examples

A sample commit message:

Longer messages are possible, but commonly not used, since the drupal.org issue already contains detailed information and is automatically linked in the release notes if you are following this guide.

Extended commit message, including non-technical explanation:

Longer, and more descriptive, for larger issues:

For other examples, have a look at commit messages as available on http://drupal.org/cvs. Note however, that you'll also see non-conforming commit messages there.