Commit Message Body

Basic Format

...

The following illustrates the basic outline for commit messages:

...

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

Gerrit

Gerrit supports auto-closing and commenting of uploaded reviews by referencing an issue.

...

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, simply referencing reference the issue is sufficientwith a Resolves or Fixes commit message trailer as follows:

ASTERISK-1234

Note that this can be done anywhere in the text of the issue.

Solution Attribution

To properly attribute a patch use the following notation:

ASTERISK-1234
patches:
  fix_bug_1234.diff submitted by SomeDeveloper (license 5678)

If multiple patches are being applied, provide a comment for each author:

ASTERISK-1234
patches:
 fix_bug_1234.diff submitted by SomeDeveloper (license 5678)
 tweak_1234.diff submitted by AnotherDeveloper (license 8765)

To include additional reporters:

ASTERISK-1234
Reported by: SomeGuy

To include testers (which cannot be inferred from the issue):

ASTERISK-1234
Tested by: AnotherGuy

All of this information can be chained together:

ASTERISK-1234
Reported by: SomeGuy
Tested by: SomeGuy
patches:
 fix_bug_1234.diff submitted by SomeDeveloper (license 5678)

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:

ASTERISK-1234
Reported by: SomeGuy

ASTERISK-4567
Reported by: AnotherGuy

Example Commit Message

What you might write:

core/db: Fix DBDelTree error codes for AMI, CLI and AGI.

The AMI DBDelTree command will return Success/Key tree deleted
successfully even if the given key does not exist. The CLI command
'database deltree' had a similar problem, but was saved because it
actually responded with '0 database entries removed'. AGI had a
slightly different error, where it would return success if the database
was unavailable.

This came from confusion about the ast_db_deltree retval, which is -1
in the event of a database error, or number of entries deleted
(including 0 for deleting nothing).

* Changed some poorly named res variables to num_deleted
* Specified specific errors when calling ast_db_deltree (database
  unavailable vs. entry not found vs. success)
* Fixed similar bug in AGI database deltree, where 'Database
  unavailable' results in successful result

ASTERISK-967
Reported by: John Bigelow
Tested by: John Bigelow

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:

app_foo.c: Add new 'x' argument to the Foo application
 
The Foo application now has an addition argument 'x' that can manipulate
the output RTP stream of the remote channel by causing it to pause for
a configured amount of time, at a configured interval and a configured
number of times.  There's no real use for this other as an example of
how to format a commit message.  
 
The code required changes to a number of other modules and is fairly
invasive and poorly written.  It also required removing an option from
the existing OldFoo application.
 
Fixes: #666
 
UserNote:  The Foo dialplan application now takes an additional argument
'x(a,b,c)' which will cause the remote channel to pause RTP output for
'a' milliseconds, every 'b' milliseconds, a total of 'c' times.
 
UpgradeNote: The X argument to the OldFoo application has been removed
and will cause an error if supplied.