A commit message serves to notify others of the changes made to the Asterisk source code, both in a historical sense and in the present. Commit messages are incredibly important to the continued success of the Asterisk project. Developers maintaining the Asterisk project in the future will often only have your commit message to guide them in why a particular change was made. For non-developers, archives containing commit messages may be used when searching for fixes to a particular bug. Be sure that the information contained in your message will help them out.
This page describes the expected format for commit messages used when submitting code to the Asterisk project. See Gerrit Usage for more information about pushing your commit for review.
Basic Format for Commit Messages
The following illustrates the basic outline for commit messages:
Your summary should, if possible, be preceded by the subsystem(s) affected by the change:
Some commit history viewers treat the first line of commit messages as the summary for the commit. In addition, the Asterisk project uses many scripts that parse commit messages for a variety of purposes. So, an effort should be made to format our commit messages in this fashion. The verbose description may contain multiple paragraphs, itemized lists, etc. Always end the first sentence (and any subsequent sentences) with punctuation.
Commit messages should be wrapped at 80 columns.
Note that for trivial commits, such as fixes for spelling mistakes, the verbose description may not be necessary.
Special Tags for Commit Messages
Gerrit supports auto-closing and commenting of uploaded reviews by referencing an issue.
To have a commit noted in an issue and to also close the issue, simply referencing the issue is sufficient:
Note that this can be done anywhere in the text of the issue.
To properly attribute a patch use the following notation:
If multiple patches are being applied, provide a comment for each author:
To include additional reporters:
To include testers (which cannot be inferred from the issue):
All of this information can be chained together:
If the patch being committed was written by the person doing the commit, and is not available to reference as an upload to the issue, there is no need to include something like "fixed by me", as that will be the default assumption when a specific patch is not referenced.
You can find a contributors license number by clicking on their name, or pulling up their profile within JIRA.
Tagging multiple issues in a single commit message
If you have a very simple commit that affects and closes multiple issues you can follow this example format:
Example Commit Message
What you might write: