[wwwdocs] Updates to contribute.html for git-friendly posting rules

Message ID c3928f40-2d71-fb5b-f2e0-3878ac88a2b7@arm.com
State New
Headers show
Series
  • [wwwdocs] Updates to contribute.html for git-friendly posting rules
Related show

Commit Message

Richard Earnshaw (lists) Jan. 9, 2020, 10:43 a.m.
The thread on gcc@ is now so long and complicated that this proposal 
back at the start has dropped off the radar.  With the switch now 
imminent I'd like to re-propose this change, this time more formally.

The text below draws heavily on the glibc equivalent rules in an attempt 
to bring some harmony, but it inevitably has some local customizations 
because these aren't the same project.

OK?

R.

Comments

Gerald Pfeifer Jan. 19, 2020, 2:09 p.m. | #1
Hi Richard,

On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote:
> The thread on gcc@ is now so long and complicated that this proposal 

> back at the start has dropped off the radar.  With the switch now 

> imminent I'd like to re-propose this change, this time more formally.


I wasn't sure *who* would best approve this since it's more a policy
question than anything else, but let's unstall this...


There's a general note I'd make, partly based on my going through
some of our older web contents recently (and "decluttering" some 
of it), and some specific feedback.


The general note is that we've had a tendency to be very specific 
in some of our policies (see the last hunk of 
https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an 
example) which can make appear us not very inviting to new blood.

That is, if all I wanted is to submit a simple patch for a typo
somewhere, how would I feel about our set of instructions, and
now this addition? 

Is there a way to make this more light weight or less complex/
optional for simple contributions?


+<h3>Email subject lines</h3>

If I interpret both Merriam-Webster and the OED correctly, "e-mail"
is the preferrable spelling?

+Your contribution email subject line will become the first line of the
+commit message for your patch.

<p> ... </p> around paragraphs (throughout).

+<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>

I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in
our archives.

Should this all really move into the remainder of the subject line/
first line of the commit message?  I guess this is a key part change
as part of your proposal?

+<h4>Component tags</h4>

Alternately we could use [PATCH,fortran], [committed,C++],... ?


Actually, if we use PATCH, RFC,... for everything else, could
COMMITTED be omitted?  That feels like a bit of shouting (so if
we keep that, at least make it lower case)?


+A component tag is a short identifier that identifies the part of the
+compiler being modified, this is important as it highlights to

Full stop: "...modified. This is..." or, better "...modified. This
highlights..." which is shorter.


I believe this could benefit from some examples of overall subject
lines.  In fact, perhaps start with examples and describe the individual
components?


As for next steps, can you please mail the (updated) proposal to
the gcc@ list?  Some, even quite prominent contributors, do not
follow gcc-patches at all (or not close) and this is bigger policy 
question that will be interesting to the broad group.

Hope this helps,
Gerald
Richard Earnshaw (lists) Jan. 20, 2020, 11:45 a.m. | #2
On 19/01/2020 14:09, Gerald Pfeifer wrote:
> Hi Richard,

> 

> On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote:

>> The thread on gcc@ is now so long and complicated that this proposal

>> back at the start has dropped off the radar.  With the switch now

>> imminent I'd like to re-propose this change, this time more formally.

> 

> I wasn't sure *who* would best approve this since it's more a policy

> question than anything else, but let's unstall this...

> 

> 

> There's a general note I'd make, partly based on my going through

> some of our older web contents recently (and "decluttering" some

> of it), and some specific feedback.

> 

> 

> The general note is that we've had a tendency to be very specific

> in some of our policies (see the last hunk of

> https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an

> example) which can make appear us not very inviting to new blood.

> 

> That is, if all I wanted is to submit a simple patch for a typo

> somewhere, how would I feel about our set of instructions, and

> now this addition?

> 

> Is there a way to make this more light weight or less complex/

> optional for simple contributions?


The more we make the process lightweight for contributors, the more work 
we make for maintainers.  If the contribution is sent correctly, then 
ideally, the patch can be applied with just 'git am' by the maintainer. 
So while we shouldn't overburden things, we shouldn't go too far.  I 
don't think we've added anything that glibc don't already require, for 
example, or many other git-based development communities.

> 

> 

> +<h3>Email subject lines</h3>

> 

> If I interpret both Merriam-Webster and the OED correctly, "e-mail"

> is the preferrable spelling?

> 

> +Your contribution email subject line will become the first line of the

> +commit message for your patch.

> 


Changed - I note that there are some other uses of 'email' on the web 
pages.  I'm not fixing those.

> <p> ... </p> around paragraphs (throughout).

> 


Done.

> +<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>

> 

> I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in

> our archives.


the [] annotation makes life harder for 'git am' as it automatically 
strips such prefixes when applying the patch.  'git am --keep-non-patch' 
can avoid stripping such tags, but it's a bit of a mouthful to keep 
typing it.  Git communities (including glibc) generally use <topic>: 
these days, so this aligns with that.
> 

> Should this all really move into the remainder of the subject line/

> first line of the commit message?  I guess this is a key part change

> as part of your proposal?

> 


The point is to get a good, concise summary that appears in "git log 
--oneline" showing the history of commits.  Moving it to the body breaks 
that.

> +<h4>Component tags</h4>

> 

> Alternately we could use [PATCH,fortran], [committed,C++],... ?

> 


Please, no.  See comment about stripping above.

> 

> Actually, if we use PATCH, RFC,... for everything else, could

> COMMITTED be omitted?  That feels like a bit of shouting (so if

> we keep that, at least make it lower case)?

> 


This is about consistency across the communities that use git.

> 

> +A component tag is a short identifier that identifies the part of the

> +compiler being modified, this is important as it highlights to

> 

> Full stop: "...modified. This is..." or, better "...modified. This

> highlights..." which is shorter.

> 


Fixed.

> 

> I believe this could benefit from some examples of overall subject

> lines.  In fact, perhaps start with examples and describe the individual

> components?

> 

> 

> As for next steps, can you please mail the (updated) proposal to

> the gcc@ list?  Some, even quite prominent contributors, do not

> follow gcc-patches at all (or not close) and this is bigger policy

> question that will be interesting to the broad group.

> 


I sent the proposal to gcc@ last year on the basis that this was policy 
rather than a simple technical change, but it didn't make any progress 
(the thread got rather bogged down with other unrelated discussions). 
Anyway, patches are supposed to go to gcc-patches, even for the web 
pages, aren't they?

I'll send the update to both lists...

R.

> Hope this helps,

> Gerald

>
Segher Boessenkool Feb. 3, 2020, 3:34 p.m. | #3
(Old thread, first time I see it though):

On Mon, Jan 20, 2020 at 11:45:28AM +0000, Richard Earnshaw (lists) wrote:
> The more we make the process lightweight for contributors, the more work 

> we make for maintainers.  If the contribution is sent correctly, then 

> ideally, the patch can be applied with just 'git am' by the maintainer. 


Almost always the maintainer will want to do "git am" followed by
"git commit --amend" *anyway*.  It helps if people follow the same
format often, but making this a stringent requirement, even before we
have experience with it, is just wrong, and does not help anyway.


Segher

Patch

diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 381aa02a..99d5b73e 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -262,6 +262,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