qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > Subversion Commit Comment Format
Date Mon, 14 Feb 2011 23:27:00 GMT
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
<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://cwiki.apache.org/confluence/display/qpid/Subversion+Commit+Comment+Format">Subversion
Commit Comment Format</a></h2>
    <h4>Page  <b>added</b> by             <a href="https://cwiki.apache.org/confluence/display/~andrew.kennedy">Andrew
    <div class="notificationGreySide">
         <h1><a name="SubversionCommitCommentFormat-CommitHookProposal"></a>Commit
Hook Proposal</h1>

<p>The vote to add a Subversion commit hook to enforce JIRA ids in commit messages was
proposed in this <a href="http://mail-archives.apache.org/mod_mbox/qpid-dev/201102.mbox/%3cAANLkTikHvTBvK_RFUEFHujz+AArDEL3_qSF+L11uZBMk@mail.gmail.com%3e"
class="external-link" rel="nofollow">thread</a> on the <tt>dev@qpid.apache.org</tt>
mailing list.</p>

<p><em>On 14 Feb 2011, at 16:53, Robbie Gemmell wrote:</em></p>
<p>add a pre-commit hook to enforce<br/>
use of JIRA references where appropriate. One suggestion I made was<br/>
that this would block all commits that don't have a Qpid JIRA<br/>
reference unless they instead contained eg 'NO-JIRA', which could be<br/>
used to bypass the hook on demand. Any commit which failed to meet<br/>
these cases would be rejected with a message alerting the committer<br/>
how to resolve the issue, i.e. include a JIRA reference if appropriate<br/>
or signal their intent to bypass the requirement. This means noone<br/>
would ever be prevented from committing what they want when they want,<br/>
but still removes the possibility of JIRA references being left out<br/>
due to merely forgetting them, and means that if/when we later review<br/>
the commits we can identify where people have chosen to purposely<br/>
bypass the requirement.</p></blockquote>

<p>The following section suggests a standard format for commit messages for the Qpid

<h1><a name="SubversionCommitCommentFormat-CommitCommentFormatting"></a>Commit
Comment Formatting</h1>

<p>We <b>SHOULD</b> (<a href="http://www.ietf.org/rfc/rfc2119.txt" class="external-link"
rel="nofollow">RFC 2119</a>) standardise the formatting of the rest of the commit
comments too, albeit without automated enforcement. I suggest the following:</p>

<p>QPID-0000, QPID-0001: Summary of contents of commit</p>

<p>Description of contents and purpose of commit. Any other details of commit go here,
such as issue summary and how or why this commit fixes it. Complex issues and rationale belong
in JIRA comments, however. Related issues are referenced by id only, as PROJECT-0000.</p>

<p>Contributed by Person One &lt;person.two@example.org&gt;<br/>
Contributed by Person Two &lt;person.two@example.org&gt;</p></blockquote>

<p>In <em>JIRA</em> commit comments the JIRA id <b>MUST</b>
appear as the first characters on the first line and <b>MUST</b> be formatted
as <tt>QPID-</tt> followed by the JIRA number in decimal. This <b>MUST</b>
be a valid Qpid JIRA id from the ASF JIRA site. If multiple JIRA ids are referenced, they
should be separated by a comma and a space and kept together at the start of the first line.
There <b>MUST</b> be a colon and a space immediately following the JIRA id(s).</p>

<p>The summary on the first line <b>SHOULD</b> be a grammatically complete
sentence, but <b>MUST</b> <b>NOT</b> be terminated by a full-stop
or period.</p>

<p>In all comments a full description of the purpose of the commit <b>SHOULD</b>
be added after the summary and <b>MUST</b> be preceded by a blank line. The description
<b>MUST</b> consist of paragraphs of text with lines no longer that 80 characters.
Each paragraph <b>MUST</b> be separated by a blank line. The comment text <b>MUST</b>
<b>NOT</b> contain JIRA URLs from the ASF JIRA site. If other ASF JIRAs are referenced,
only the JIRA id <b>MUST</b> be used and <b>MUST</b> be formatted
in the same fashion the Qpid JIRA id(s) at the start of the first line.</p>

<p>In all comments, contributors other than the committer <b>MUST</b> be
identified by a valid e-mail address surrounded by angle-brackets and be preceded by their
full name. Multiple contributors <b>MUST</b> be listed on separate lines. Contributor
lists <b>MUST</b> be separated from the description or summary by a blank line.</p>

<p>NO-JIRA: Summary of contents of commit</p>

<p>Full description of contents and purpose of commit. Any other details of commit go
here, such as issue summary and how or why this commit fixes it. Complex issues and rationale
belong in JIRA comments, however.</p>

<p>External reference &lt;<a href="http://tracker.example.com/id" class="external-link"

<p>In <em>NO-JIRA</em> comments, the first characters on the first line
<b>MUST</b> be <tt>NO-JIRA</tt> and <b>MUST</b> be immediately
followed by a colon and a space and a short summary of the commit. There <b>MAY</b>
be an external reference to another bug tracking system which <b>MUST</b> be preceded
by a blank line. The reference <b>MUST</b> show the full URL of the issue on the
external site, surrounded by angle-brackets. The description <b>MUST</b> contain
a complete explanation of the reason for the commit if there is no external reference.</p>

<p>NO-JIRA: Trivial commit description</p></blockquote>

<p>In trivial <em>NO-JIRA</em> comments the description paragraph <b>MAY</b>
be omitted.</p>
    <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       <a href="https://cwiki.apache.org/confluence/display/qpid/Subversion+Commit+Comment+Format">View
       <a href="https://cwiki.apache.org/confluence/display/qpid/Subversion+Commit+Comment+Format?showComments=true&amp;showCommentArea=true#addcomment">Add

Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org

View raw message