From patchwork Tue Jan 21 14:52:00 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Richard Earnshaw (lists)"
X-Patchwork-Id: 1226616
Return-Path:
X-Original-To: incoming@patchwork.ozlabs.org
Delivered-To: patchwork-incoming@bilbo.ozlabs.org
Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized)
smtp.mailfrom=gcc.gnu.org (client-ip=209.132.180.131;
helo=sourceware.org;
envelope-from=gcc-patches-return-517889-incoming=patchwork.ozlabs.org@gcc.gnu.org;
receiver=)
Authentication-Results: ozlabs.org;
dmarc=none (p=none dis=none) header.from=arm.com
Authentication-Results: ozlabs.org; dkim=pass (1024-bit key;
unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org
header.a=rsa-sha1 header.s=default header.b=xb4cLdYI;
dkim-atps=neutral
Received: from sourceware.org (server1.sourceware.org [209.132.180.131])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256
bits)) (No client certificate requested)
by ozlabs.org (Postfix) with ESMTPS id 482BMr4MyXz9sRk
for ;
Wed, 22 Jan 2020 01:52:23 +1100 (AEDT)
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id
:list-unsubscribe:list-archive:list-post:list-help:sender
:subject:from:to:cc:references:message-id:date:mime-version
:in-reply-to:content-type; q=dns; s=default; b=Nind9HpTbkhSOAKi8
7owViKWm7/vKUbsL/dLouf2P6D8e8a6rlEnHq70tPdVdoVeT3wzbCYvBb/MTtHlN
G2lGP8rIk3d672nckA3bNMBDXOeDRSUu6d0/3PKVEcR2sP4vRKrAXZnJaPCOdSsJ
l9meLMukpMno23w6yS9lbJI7Ps=
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id
:list-unsubscribe:list-archive:list-post:list-help:sender
:subject:from:to:cc:references:message-id:date:mime-version
:in-reply-to:content-type; s=default; bh=kHPE4tRiCoVzCZIOl1T6fMo
TZ2M=; b=xb4cLdYIxk+5+czZlIg14ev0wVYevyCFnKeT+W/GpyVCpO/C2ut6Qqs
lUEWAxS+IosF+kd/uGNqNKaPbqY8cqtV/LYHhRI7NFQyGbCrGJn/Zl3FZsMojNRQ
3pFES4goF5DYO+Rlh23WPAlS+tTgaeI5ENCc4c6A8uLZJLgjL6s8=
Received: (qmail 91211 invoked by alias); 21 Jan 2020 14:52:15 -0000
Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm
Precedence: bulk
List-Id:
List-Unsubscribe:
List-Archive:
List-Post:
List-Help:
Sender: gcc-patches-owner@gcc.gnu.org
Delivered-To: mailing list gcc-patches@gcc.gnu.org
Received: (qmail 91197 invoked by uid 89); 21 Jan 2020 14:52:14 -0000
Authentication-Results: sourceware.org; auth=none
X-Spam-SWARE-Status: No, score=-18.8 required=5.0 tests=AWL, BAYES_00,
GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3,
RCVD_IN_DNSWL_LOW,
SPF_PASS autolearn=ham version=3.3.1 spammy=Series, marker,
E-mail
X-HELO: foss.arm.com
Received: from foss.arm.com (HELO foss.arm.com) (217.140.110.172) by
sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP;
Tue, 21 Jan 2020 14:52:04 +0000
Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by
usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id
A4AA730E; Tue, 21 Jan 2020 06:52:02 -0800 (PST)
Received: from e120077-lin.cambridge.arm.com (e120077-lin.cambridge.arm.com
[10.2.78.81]) by usa-sjc-imap-foss1.foss.arm.com (Postfix)
with ESMTPSA id 1A00B3F52E; Tue, 21 Jan 2020 06:52:01 -0800 (PST)
Subject: [PATCH, v2] wwwdocs: e-mail subject lines for contributions
From: "Richard Earnshaw (lists)"
To: Gerald Pfeifer
Cc: gcc-patches@gcc.gnu.org, GCC Development
References:
<353faf3e-bf43-eb4d-542d-45a53dce77b2@arm.com>
Message-ID:
Date: Tue, 21 Jan 2020 14:52:00 +0000
User-Agent: Mozilla/5.0 (X11; Linux x86_64;
rv:60.0) Gecko/20100101 Thunderbird/60.9.0
MIME-Version: 1.0
In-Reply-To: <353faf3e-bf43-eb4d-542d-45a53dce77b2@arm.com>
[updated, following some comments from Gerald, main differences are
slight tweaks to the html markup and changing "email" to "e-mail"]
This patch proposes some new (additional) rules for email subject lines
when contributing to GCC. The goal is to make sure that, as far as
possible, the subject for a patch will form a good summary when the
message is committed to the repository if applied with 'git am'. Where
possible, I've tried to align these rules with those already in
use for glibc, so that the differences are minimal and only where
necessary.
Some things that differ from existing practice (at least by some people)
are:
- Use ':' rather than '[]'
- This is more git friendly and works with 'git am'.
- Put bug numbers at the end of the line rather than the beginning.
- The bug number is useful, but not as useful as the brief summary.
Also, use the shortened form, as the topic part is more usefully
conveyed in the proper topic field (see above).
diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index 042ff069..861f7e5e 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -249,13 +249,98 @@ 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.)
+E-mail subject lines
+
+Your contribution e-mail subject line will become the first line of
+the commit message for your patch.
+
+A high-quality e-mail subject line for a contribution contains the
+following elements:
+
+
+ - A classifier
+ - Component tags
+ - An optional series identifier
+ - A brief summary
+ - An optional bug number
+
+
+Classifier
+
+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 e-mail subject line that will not appear in the commit itself.
+The classifier may optionally contain a version number (vN) and
+a series marker (N/M). Examples are:
+
+
+ [PATCH]
- a single patch
+ [PATCH v2]
- the second version of a single patch
+ [PATCH 3/7]
- the third patch in a series of seven
+ patches
+ [RFC]
- a point of discussion, may contain a patch
+ [COMMITTED]
- a patch that has already been committed.
+
+
+Component tags
+
+A component tag is a short identifier that identifies the part of
+the compiler being modified. This highlights to the 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,
+
+
+ libstdc++:
+ combine:
+ vax: testsuite:
+
+
+Series identifier
+
+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 short string that identifies the series (it is common to all
+patches) and should be followed by a single dash surrounded by white
+space.
+
+Brief summary
+
+The brief summary encapsulates in a few words the intent of the
+change. For example: cleanup check_field_decls
.
+
+Bug number
+
+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 (PRnnnnn) without the bugzilla component
+identifier.
+
+Other messages
+
+Some large patch sets benefit from an introductory e-mail 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: [PATCH
+0/7]
. 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 e-mail 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.
+
Pinging patches, Getting patches applied
If you do not receive a response to a patch that you have submitted
within two weeks or so, it may be a good idea to chase it by sending a
-follow-up email to the same list(s). Patches can occasionally fall through
-the cracks. Please be sure to include a brief summary of the patch and the
-URL of the entry in the mailing list archive of the original submission.
+follow-up e-mail to the same list(s). Patches can occasionally fall
+through the cracks. Please be sure to include a brief summary of the
+patch and the URL of the entry in the mailing list archive of the
+original submission.
If you do not have write access and a patch of yours has been approved,
but not committed, please advise the approver of that fact. You may want