Last updated 28 November 2015.
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.
It is also a good practice and a form of netiquette to credit contribution authors both in commit messages and in the commits themselves by properly applying git aware patches. Thus, the commit will appear in contributor's profile and will help spread good karma and encourage further contributions.
The Credit & committing section of an issue will automatically format commit messages for you, including --author attribution, so that you can just edit the message (it defaults to the issue title) as needed.
Providing non-code issue credits
Note that the Credit & committing UI also allows maintainers to save credit for the issue itself (outside of the git repository). This will record the efforts of all contributors and their attributed organizations, and that data will then be available for display on their Drupal.org profiles.
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]
Issue #52287 by sun, Dries: Fixed outdated commit message standards
Note the punctuation.
At the bottom of each issue, there is a fieldset named "Credit and committing". It gives you a nice commit message for any issue.
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
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 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.
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 (eg. more than 10-12) 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
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.
You can also add a commit author in git to attribute authorship of what you're committing to another user.
(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:
- Apply a patch.
- 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.
- Copy the changelog entry and re-use for the Git commit message (but remove linefeeds and indents of long lines).
- Prepend the "
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 126.96.36.199 +++ 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
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.