<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Commit+Messages">Commit Messages</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~rnewton">Rusty Newton</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
added an example format for "tagging multiple issues in a single commit message"<br />
</div>
<br/>
<h4>Changes (1)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >You can find a contributors license number by clicking on their name, or pulling up their profile within JIRA. <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Tagging multiple issues in a single commit message <br> <br>If you have a very simple commit that affects or closes multiple issues you can follow this example format: <br> <br>{noformat} <br>(closes issue ASTERISK-1234) <br>Reported by: SomeGuy <br>(closes issue ASTERISK-5678) <br>Reported by: AnotherGuy <br>{noformat} <br> <br></td></tr>
<tr><td class="diff-unchanged" >h2. Review Board (https://reviewboard.asterisk.org/) <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div>
<ul>
<li><a href='#CommitMessages-CommitMessage%3F'>1. Commit Message?</a></li>
<li><a href='#CommitMessages-BasicFormatforCommitMessages'>2. Basic Format for Commit Messages</a></li>
<li><a href='#CommitMessages-SpecialTagsforCommitMessages'>3. Special Tags for Commit Messages</a></li>
<ul>
<li><a href='#CommitMessages-JIRA%28https%3A%2F%2Fissues.asterisk.org%2Fjira%2F%29'>3.1. JIRA ( https://issues.asterisk.org/jira/)</a></li>
<ul>
<li><a href='#CommitMessages-Taggingmultipleissuesinasinglecommitmessage'>3.1.1. Tagging multiple issues in a single commit message</a></li>
</ul>
<li><a href='#CommitMessages-ReviewBoard%28https%3A%2F%2Freviewboard.asterisk.org%2F%29'>3.2. Review Board ( https://reviewboard.asterisk.org/)</a></li>
</ul>
<li><a href='#CommitMessages-ExampleCommitMessage'>4. Example Commit Message</a></li>
<li><a href='#CommitMessages-CommitMessageswithsvnmerge'>5. Commit Messages with svnmerge</a></li>
<li><a href='#CommitMessages-EditingtheSubversionlog'>6. Editing the Subversion log</a></li>
</ul></div>
<h1><a name="CommitMessages-CommitMessage%3F"></a>1. Commit Message?</h1>
<p>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. After a commit, an E-mail with your commit message will be sent out to the <a href="http://lists.digium.com/mailman/listinfo/asterisk-commits" class="external-link" rel="nofollow">asterisk-commits mailing list</a>.</p>
<p>This page describes the expected format for commit messages used when committing code to the Asterisk project via subversion. Typically the message will be consumed during commit by a command like the following:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ svn commit -F ../commitmessage.txt
</pre>
</div></div>
<p>Often, archives containing commit messages may be searched by someone looking to find a fix for their bug. Be sure that the information contained in your message will help them out.</p>
<h1><a name="CommitMessages-BasicFormatforCommitMessages"></a>2. Basic Format for Commit Messages</h1>
<p>The following illustrates the basic outline for commit messages:<br class="atl-forced-newline" /> </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false"><One-liner summary of changes>
<Empty Line>
<Verbose description of the changes>
<Empty Line>
<Special Tags></pre>
</div></div>
<p>Some commit history viewers treat the first line of commit messages as the summary for the commit. So, an effort should be made to format our commit messages in that fashion. The verbose description may contain multiple paragraphs, itemized lists, etc. Always end the first sentence (and any subsequent sentences) with punctuation.</p>
<p>Commit messages should be wrapped at 80 columns.</p>
<p>Note that for trivial commits, such as "fix the build", or "fix spelling mistake", the verbose description may not be necessary.</p>
<h1><a name="CommitMessages-SpecialTagsforCommitMessages"></a>3. Special Tags for Commit Messages</h1>
<h2><a name="CommitMessages-JIRA%28https%3A%2F%2Fissues.asterisk.org%2Fjira%2F%29"></a>3.1. JIRA (<a href="https://issues.asterisk.org/jira/" class="external-link" rel="nofollow">https://issues.asterisk.org/jira/</a>)</h2>
<p>To have a commit noted in an issue, use a tag of the form:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>(issue ASTERISK-1234)
</pre>
</div></div>
<p>To have a commit automatically close an issue, use a tag of the form:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>(closes issue ASTERISK-1234)
</pre>
</div></div>
<p>Also include information about who reported an issue, or who contributed testing feedback:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>(closes issue ASTERISK-1234)
Reported by: SomeGuy
Tested by: SomeOtherGuy, SomeOtherGuy2
Patches:
fix_bug_1234.diff uploaded by SomeDeveloper (license 5678)
</pre>
</div></div>
<p>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.</p>
<p>You can find a contributors license number by clicking on their name, or pulling up their profile within JIRA.</p>
<h3><a name="CommitMessages-Taggingmultipleissuesinasinglecommitmessage"></a>3.1.1. Tagging multiple issues in a single commit message</h3>
<p>If you have a very simple commit that affects or closes multiple issues you can follow this example format:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>(closes issue ASTERISK-1234)
Reported by: SomeGuy
(closes issue ASTERISK-5678)
Reported by: AnotherGuy
</pre>
</div></div>
<h2><a name="CommitMessages-ReviewBoard%28https%3A%2F%2Freviewboard.asterisk.org%2F%29"></a>3.2. Review Board (<a href="https://reviewboard.asterisk.org/" class="external-link" rel="nofollow">https://reviewboard.asterisk.org/</a>)</h2>
<p>To have a commit set a review request as submitted, include the full URL to the review request. For example:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>Review: https://reviewboard.asterisk.org/r/95/
</pre>
</div></div>
<h1><a name="CommitMessages-ExampleCommitMessage"></a>4. Example Commit Message</h1>
<p>What you might write:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>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
(closes issue AST-967)
Reported by: John Bigelow
Review: https://reviewboard.asterisk.org/r/2138/
</pre>
</div></div>
<h1><a name="CommitMessages-CommitMessageswithsvnmerge"></a>5. Commit Messages with svnmerge</h1>
<p>When using the svnmerge tool for merging changes between branches, use the <em>commit message generated by svnmerge</em>. The '-F' option to svnmerge allows you to specify a file for <em>svnmerge</em> to write out a commit message to. The '-F' option to svn commit allows you to specify a file that contains the commit message.</p>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>If you are using the <a href="https://wiki.asterisk.org/wiki/display/AST/Subversion+Usage#SubversionUsage-BranchMergingOrder" class="external-link" rel="nofollow">expect script wrappers for svnmerge from repotools</a>, a commit message is automatically placed in the file '../merge.msg'.</td></tr></table></div>
<p>For more detailed information about working with branches and merging, see <a href="/wiki/display/AST/Subversion+Usage" title="Subversion Usage">Subversion Usage</a>.</p>
<h1><a name="CommitMessages-EditingtheSubversionlog"></a>6. Editing the Subversion log</h1>
<p>To edit the SVN log to include some missing information or correct an error simply use the revision number.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>svn propedit svn:log --revprop -r 123456
</pre>
</div></div>
<p>For the revision 123456 you will load the commit log message in your commit editor. From there you can update the log and save. The log will be updated upon save.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Commit+Messages">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=3702833&revisedVersion=13&originalVersion=12">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Commit+Messages?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>