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

[Gerald Pfeifer]

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