From patchwork Wed Jan 22 17:45:06 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: 182922 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp5359136ile; Wed, 22 Jan 2020 09:46:37 -0800 (PST) X-Google-Smtp-Source: APXvYqwpPSRIU4rkGFnCYJ0jNukDSY0UbImMy+Lc34tnWK/K76Sr3Bhjzd2b4mr6twAu92lcSzHF X-Received: by 2002:a05:6830:1481:: with SMTP id s1mr8145190otq.66.1579715196895; Wed, 22 Jan 2020 09:46:36 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1579715196; cv=none; d=google.com; s=arc-20160816; b=DC24BSqRru98Lo8IecfNPcUoOzr7Cc3Wg9GdnWz+vwyPCT1jpkGpYQ2KH3bG/6NUfR 8L73hVUBoXOGj7en18b3dERNH+uU/1REZ1/u8bVVFoUvgWO3wZlhH8OejWe8iaOrkeUU NGe0KaSLakhGUQmHyY3fWPdFvHCI724m4SebBBsyIfAXYifaXDIc2cZH9P/Sge3YlEFI 0shVsRBUWYSCCu8xHqRt3xWAHmELHBli6AyRAi0l6Cn/0q1dbnXtieQEh2NDvO8V6w+0 ast21o79sTBJ6niVe9eEIlNfmiG5aup4geXAjb6OpRMLHGpZPazXgtUYgKTB5DdMtyHi XNWw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=in-reply-to:mime-version:user-agent:date:message-id:references:cc :to:from:subject:delivered-to:sender:list-help:list-post :list-archive:list-unsubscribe:list-id:precedence:mailing-list :dkim-signature:domainkey-signature; bh=aExV1WdggWErnWUyweymPRr+R2v/mwYxAfkv3tsARvQ=; b=RM/JCBEpxQEyeCgtsp/cFHhq6prhT/JfR4gG5Hx/+E6rIaDkvsExZI8uo87TbVV9GI w7o29gOFRO1JLaH0YWfym6bdU/N3gdWcpEwfp/HINbnmtOFrp15dSQAb8ENqzpeqnl5/ BMbtHfEepe2Vm6sfysuue0QFvVOk3+TdOkRmReQbOXT5wHwQCN/vgenjuBW3NFgUnlk3 Qpbx6dQiy0VtO1FfXM25yYBQZs/bnWwfZtzMRfYQhoOC/dgfATI9GbLd29kqbsAqfBxk 8qS9TWg1nkaVADzJadEGwN2vkUlQNXOmn87ltA9kdmFSaClcxrr44kxvHK8FWUg+9shH PhLg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=UDZU1B03; spf=pass (google.com: domain of gcc-patches-return-518051-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom="gcc-patches-return-518051-patch=linaro.org@gcc.gnu.org" Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id h138si21308993oib.6.2020.01.22.09.46.36 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 22 Jan 2020 09:46:36 -0800 (PST) Received-SPF: pass (google.com: domain of gcc-patches-return-518051-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@gcc.gnu.org header.s=default header.b=UDZU1B03; spf=pass (google.com: domain of gcc-patches-return-518051-patch=linaro.org@gcc.gnu.org designates 209.132.180.131 as permitted sender) smtp.mailfrom="gcc-patches-return-518051-patch=linaro.org@gcc.gnu.org" 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=JxCxCscDOnaxibaA0 xAdK/AboD+kkfJiCWM80rs8ypgP0AGwROwJtcseCfah069TiW7BLmxORta9AuSyj mnwmL8+XqFyZSqkL7GN5UCA/4Qd/5viZjyFUzYcVYwmQ4nnEAxBu6G5AvOiamchy /Swat+JYTTO5FJJ7RJV3qDKM6Q= 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=qL/t40CCudzTZQ1ZJo5t2dP 39MA=; b=UDZU1B03HaZjEig57D7dQCX21eoah6JF2R9FUrmSEv71tEWo7kp+tdt kMv2Zh/1TZpurU6ChAqAB73F7S+oeqTGzjWBfuNewC3S4KVs6QsCAjm37M9NuSLB a2wPWGb0MDV4f6iQt9QoE+XOriOnyIXWL9mLdCtpMxDHJ62y7FTg= Received: (qmail 101974 invoked by alias); 22 Jan 2020 17:45:56 -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 101859 invoked by uid 89); 22 Jan 2020 17:45:41 -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=becoming 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; Wed, 22 Jan 2020 17:45:21 +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 61B4B1FB; Wed, 22 Jan 2020 09:45:08 -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 CA4713F6C4; Wed, 22 Jan 2020 09:45:07 -0800 (PST) Subject: [PATCH, v3] 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: <91e48c52-4548-089b-707a-afd400001dac@arm.com> Date: Wed, 22 Jan 2020 17:45:06 +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: [updated based on v2 discussions] 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..558bae29 100644 --- a/htdocs/contribute.html +++ b/htdocs/contribute.html @@ -249,13 +249,143 @@ 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
    • +
+ +

The entire line (excluding the classifier) should not exceed 75 +characters.

+ +

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

Some large components may be subdivided into sub-components. If +the subcomponent name is not disctinct in its own right, you can use the +form component/sub-component:.

+ +

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.

+ +

A Very Brief summary

+ +

The brief summary encapsulates in a few words the intent of the +change. For example: cleanup check_field_decls. +Although, very short, the summary should be distinct so that it will +not be confused with other patches.

+ +

Bug number

+ +

If your patch relates 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 and with no space between 'PR' and the number. +The body of the commit message should still contain the full form +(PR <component>/nnnnn) within the body of +the commit message so that Bugzilla will correctly notice the +commit. If your patch relates to two bugs, then write +[PRnnnnn, PRmmmmm]. For multiple +bugs, just cite the most relevant one in the summary and use an +elipsis instead of the second, or subsequent PR numbers; list all the +related PRs in the body of the commit message in the normal way.

+ +

It is not necessary to cite bugs that are closed as duplicates of +another unless there is something specific to that report that +is not covered by the parent bug.

+ +

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.

+ +

If you submit a new version of a patch series, then you should +start a new email thread (don't reply to the original patch series). +This avoids email threads becoming confused between discussions of the +first and subsequent revisions of the patch set. Your cover leter +(0/nnn) should explain clearly what has been changed between +the two patch series. Also state if some of the patches are unchanged +between revisions; this saves maintainers having to re-review the +patches they might have already reviewed in an earlier version. The +individual patch messages should be as you expect them to be +committed. It is a good idea to send a final follow-up message to the +original thread indicating that a new version has been submitted.

+ +

Examples

+ +

Here are some complete examples, based on real commits to GCC.

+ +
    +
  • [COMMITTED] libstdc++: Fix freestanding build [PR92376]
    • +
  • [PATCH 1/6] analyzer: Fix tests for UNKNOWN_LOCATION
    • +
  • [RFC] doc: Note that some warnings depend on optimizations [PR92757]
    • +
  • [COMMITTED] c++: coroutines - Initial implementation
    • +
  • [PATCH v2] wwwdocs: E-mail subject lines for contributions
    • +
+

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