Skip to end of metadata
Go to start of metadata

Commit Messages

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.

Follow These Guidelines

Icon

Commit messages are part of your code change. Committing code with a poorly written commit message creates a maintenance problem for everyone in the Asterisk project.

As such, your commit message is part of your code review. Code submissions with a poorly written commit message or one that fails to use the appropriate headers listed on this page will not be accepted.

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.

On This Page

 

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

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

Icon

If you do not reference an issue when you submit a review the review tool will remind you that you should. While it is not currently required to include an issue in the commit message it is highly preferred.

 

Issue Referencing

To have a commit noted in an issue and to also close the issue, simply referencing the issue is sufficient:

ASTERISK-1234

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

Solution Attribution

Icon

The scripts used to create Asterisk releases parse the solution attribution information to create the release summaries. Care should be taken to follow the formatting guidelines exactly.

 

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)
Icon

Various tools parse commit message in order to build out release summaries, notifications, and other information.

Patch submitters, testers, and issue reporters should be done as separate comments.

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
  • No labels

2 Comments

  1. Maybe add a note about #close near "Issue referencing"? See Issue Tracker Workflow#Notes

    1. Late response, sorry.  The #close keyword after the issue is no longer needed and will be ignored if specified.  I've updated the note on the Workflow page.