Commit messages - providing history and credit

 

As a module or theme maintainer or contributor, you may be making commits to a Drupal Git 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.

Important: Do NOT begin your commit message with the # symbol. While this was a best practice with CVS, it will cause Git to remove the commit message entirely in certain situations (e.g. git rebase -i).

Quick summary for the impatient

Use this syntax for commit messages:

Issue #[issue number] by [comma-separated usernames]: [Short summary of the change].

For example:

Issue #52287 by sun, Dries: Fixed outdated commit message standards.

Note the punctuation.

Longer version

Give details

Provide at least a short summary of what is contained in the commit. Most often, the issue title can be re-used. Otherwise, try to summarize the change.

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

  • Added (new feature)
  • Fixed (bug fix)
  • Changed (task)
  • Updated (task, due to changes in third-party code)

It may not be trivial to phrase a summary starting with one of those verbs. But if used consistently, you will get used to it. When not using these verbs, make sure you prefix the commit message with the issue category.

Either way allows users of your module to determine whether a new release contains only bug fixes or maybe also new features and 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.

Reference the drupal.org issue, if available

A common practice 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 number/pound/hash sign (#). This convention is interpreted by the commit log on drupal.org to provide a link back to the issue.

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 yourself. 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.

Issue #123456 by dww, Dries: Added project release tracking.

If you are just committing a patch created by others, do not credit yourself.

If a very very large list of people contributed to a change, pick the major contributors and add et al to represent the rest:

Issue #123456 by dww, pwolanin, et al: Added project release tracking.

Listing 5-6 people individually is fine, though.

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

by sun: Updated README.txt.

Always refer to usernames from drupal.org and not the contributors' Git account names.

(Optional) Re-use commit messages in CHANGELOG.txt

Each project should include a CHANGELOG.txt, which lists the major changes to the code in the project. Some projects choose to list even minor changes.

One way to create the CHANGELOG.txt file is to copy and paste commit messages to your changelog prior to committing a change (see formatting above). This gives you a nice output for project release nodes. (Or you could bypass this completely by using the git-release-notes Drush extension -- example output.)

Note that if you do copy/paste commit messages into CHANGELOG.txt for every commit, it does make it more difficult to do git "cherry-picking" (i.e., to apply only selected patches to a new branch), and more difficult to port patches to other branches. But if you do want to follow this practice:

  1. Apply a patch.
  2. Add a change log entry to CHANGELOG.txt. Notes:
    • Change logs are reverse chronological, new entries at the top.
    • All lines in CHANGELOG.txt should wrap at 80 chars. If an entry exceeds 80 chars, subsequent lines belonging to the same entry should be indented by 2 spaces.
    • Leave out the "Issue" commit message prefix in the changelog.
  3. Copy the changelog entry and re-use for the Git commit message (but remove linefeeds and indents of long lines).
  4. Prepend the "Issue " prefix.
  5. Commit.

Normally, changelog entries/changes shouldn't be contained in patches you create and submit to a project. Let the project maintainer add CHANGELOG entries.

Prior to creating a new release, you should update the CHANGELOG.txt and insert a new release heading:

--- CHANGELOG.txt 3 Nov 2008 23:18:02 -0000 1.4.2.14
+++ CHANGELOG.txt 29 Nov 2008 15:42:53 -0000
@@ -6,6 +6,10 @@ Journal x.x-x.x, xxxx-xx-xx

Journal 6.x-1.x, xxxx-xx-xx
---------------------------
+
+
+Journal 6.x-1.3, 2008-11-29
+---------------------------
#322731 by sun: Fixed improper use of t() in module install file.

Examples

A sample commit message:

Issue #46746 by Matt: Fixed inconsistent encoding of path aliases.

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:

Issue #46746 by Matt: Fixed inconsistent encoding of path aliases.

Fixes broken URLs on profile pages.

Longer, and more descriptive, for larger issues:

Issue #[issue number] by [username]: [Short summary of the change].

A bug in [filename(s)] caused [short description of the problem]. This commit
solves this by:
* [first solution or change]
* [second solution or change]
* [third solution or change]
* Adding $foo as parameter to the API call module_function() in bar.

[Optional short note on the effects for code calling your APIs or functions, or users using your modules.]

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