Re: Commit messages and the move to git

[Richard Earnshaw <Richard dot Earnshaw at arm dot com>]

On 04/11/2019 16:04, Jeff Law wrote:
> On 11/4/19 3:29 AM, Richard Earnshaw (lists) wrote:
>> With the move to git fairly imminent now it would be nice if we could
>> agree on a more git-friendly style of commit messages; and, ideally,
>> start using them now so that the converted repository can benefit from
>> this.
>
> I'd suggest we sync policy with glibc.  They're further along on the
> ChangeLog issues.  Whatever they do in this space we should follow --
> aren't we going to be using some of their hooks/scripts?
> 
> jeff
> 


OK, based on these discussions here's an initial proposal for some 
wording in contribute.html for the web site.  I've based it strongly on 
the libc version, mostly with some restructuring and a tweak around bug 
numbers.

R.

diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 80ebb26f..8f5741e5 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -261,6 +261,89 @@ that ChangeLog entries may be included as part of the patch and diffs
 representing new files may be omitted, especially if large, since they
 can be accessed directly from the repository.)</p> 
 
+<h3>Email subject lines</h3>
+
+Your contribution email subject line will become the first line of the
+commit message for your patch.
+
+A high-quality email subject line for a contribution contains the
+following elements:
+
+<ul>
+  <li>A classifier</li>
+  <li>Component tags</li>
+  <li>An optional series identifier</li>
+  <li>A brief summary</li>
+  <li>An optional bug number</li>
+</ul>
+
+<h4>Classifier</h4>
+
+The classifier identifies the type of contribution, for example a
+patch, an RFC (request for comments) or a committed patch (where
+approval is not necessary.  The classifier should be written in upper
+case and surrounded with square brackets.  This is the only component
+of the email subject line that will not appear in the commit itself.
+The classifier may optionally contain a version number (v<i>N</i>) and
+a series marker (<i>N/M</i>).  Examples are:
+
+<ul>
+  <li><code>[PATCH]</code> - a single patch</li>
+  <li><code>[PATCH v2]</code> - the second version of a single patch</li>
+  <li><code>[PATCH 3/7]</code> - the third patch in a series of seven
+    patches</li>
+  <li><code>[RFC]</code> - a point of discussion, may contain a patch</li>
+  <li><code>[COMMITTED]</code> - a patch that has already been committed.</li>
+</ul>
+
+<h4>Component tags</h4>
+
+A component tag is a short identifier that identifies the part of the
+compiler being modified, this is important as it highlights to
+relevant maintainers that the patch may need their attention.
+Multiple components may be listed if necessary.  Each component tag
+should be followed by a colon.  For example,
+
+<ul>
+  <li><code>vax: testsuite:</code></li>
+  <li><code>libstdc++:</code></li>
+  <li><code>combine:</code></li>
+</ul>
+
+<h4>Series identifier</h4>
+
+The series identifier is optional and is only relevant if a number of
+patches are needed in order to effect an overall change.  It should be
+a <i>short</i> string that identifies the series (it is common to all
+patches) and should be followed by a single dash surrounded by white
+space.
+
+<h4>Brief summary</h4>
+
+The brief summary encapsulates in a few words the intent of the
+change.  For example: <code>cleanup check_field_decls</code>.
+
+<h4>Bug number</h4>
+
+If your patch fixes a bug in the compiler for which there is an
+existing PR number the bug number should be stated.  Use the
+short-form variant (PR<i>nnnnn</i>) without the bugzilla component
+identifier.
+
+<h4>Other messages</h4>
+
+Some large patch sets benefit from an introductory email that provides
+more context for the patch series and describes how the patches have
+been broken up to provide for review.  The convention is that such
+messages should follow the same format as described above, but the
+patch number should be set to zero, for example: <code>[PATCH
+0/7]</code>.  Remember that the introductory message will not be
+committed with the patches themselves, so it should not contain any
+important information that is not also covered in the individual
+patches.  If you send a summary email with a series it is a good idea
+to send the patches as follow-ups (essentially replies) to your
+initial message so that mail software can group the messages together.
+
 <h3>Pinging patches, Getting patches applied</h3>
 
 <p>If you do not receive a response to a patch that you have submitted