Commit Message Body

Basic Format

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 72 columns.

Note that for trivial commits, such as fixes for spelling mistakes, the verbose description may not be necessary.

GitHub Flavored Markdown

Since we've moved to a complete GitHub SCM solution, commit messages will automatically be rendered as markdown when viewed on GitHub.  Feel free to use markdown intentionally, especially to format code snippets, but also be aware that things you used to put in commit messages might unintentionally be rendered as markdown and be improperly formatted.  Consider that dashes and underscores might unintentionally be rendered as strike-through or bold text.

Special Tags for Commit Messages

GitHub and our release process support several commit message trailers.  The trailer name MUST start on a new line and each should be separated by a blank line.  If specified at all, the trailers listed below MUST be the last items in the commit message.  If you specify any other trailers, including ones that were formerly acceptable, they will become part of the official trailer they follow.  so, if you insist on adding trailers like Signed-Off-By or Reported-By they MUST come before the fist of the official trailers.

Issue Referencing

To have a commit noted in an issue and to also close the issue, reference the issue with a Resolves or Fixes commit message trailer as follows:

Resolves: #45
or
Fixes: #45

The trailer must start at the beginning of a new line and contain nothing on the line after it.   The colon separator is important for the automation and the only spaces allowed are between the colon and the hash sign.  The regex for this is ^(Resolves|Fixes):\s*[#][0-9]+.  

Upgrade and User Notes

With the migration to GitHub, Changelog and Upgrade notes are no longer supplied separately in the doc/CHANGES-staging and doc/UPGRADE-staging directories.  Instead they should be supplied in the commit message as trailers.  Any user-affecting change (new feature, change to CLI commands, etc) must be documented with a UserNote: trailer.   Any breaking change (change to dialplan application or function arguments, API change, etc.) must be documented with an UpgradeNote: trailer.   Those trailers cause special notes to be output in the change log in addition to the full commit message.  Example complete commit message: