From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 55207 invoked by alias); 22 Jan 2020 10:00:06 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 55160 invoked by uid 89); 22 Jan 2020 10:00:05 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-6.3 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_PASS autolearn=ham version=3.3.1 spammy=balance 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 10:00:03 +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 F32C61FB; Wed, 22 Jan 2020 02:00:01 -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 4E1D53F68E; Wed, 22 Jan 2020 02:00:01 -0800 (PST) Subject: Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions To: Segher Boessenkool Cc: Gerald Pfeifer , gcc-patches@gcc.gnu.org, GCC Development References: <353faf3e-bf43-eb4d-542d-45a53dce77b2@arm.com> <20200121192650.GI3191@gate.crashing.org> From: "Richard Earnshaw (lists)" Message-ID: Date: Wed, 22 Jan 2020 16:05: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: <20200121192650.GI3191@gate.crashing.org> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2020-01/txt/msg00397.txt.bz2 On 21/01/2020 19:26, Segher Boessenkool wrote: > Hi! > > Thanks for doing this. > > On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: >> 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'. > >> +

A high-quality e-mail subject line for a contribution contains the >> +following elements:

> >> +
  • A brief summary
    • > > You could stress that this is the one thing that really matters. And > it's not a summary, it's much too brief for that (at most ~50 chars), > but yup it should be something that allows *a human* to identify what > this is. > Well, it should all matter, or why are we requiring it? I'm happy to insert 'very' in front of 'brief' and to say elsewhere that the entire subject (less the leading [...] part, should rarely, if ever, go beyond 80 characters. > Everything else is just convention. > >> +

    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. > > Often people use aaa/bbb: if drilling down a bit that way helps keep the > subject short (which is the *point* of all this: keep things better > consumable for humans). The aaa: bbb: is really for when aaa and bbb are independent parts of the compiler and potentially needs multiple reviewers. aaa/bbb is when bbb is strictly a sub-component of aaa (for example, arm/SVE: would be an SVE related issue in the arm backend). I'm certainly not against having that. > >> +

    The brief summary encapsulates in a few words the intent of the >> +change. For example: cleanup check_field_decls.

    > > It should start with a capital though. "Clean up blablal". (So no > dot to end the sentence, this isn't a sentence). A capital helps > the reader to quickly identify what is what, separate fluff from the > core parts. > There is a balance here to be made. I'm mindful of Gerald's concern that this is perhaps overly restrictive for new users already. I certainly think we should have a good house style, but getting too prescriptive just gets in the way of attracting good contributions. >> +

    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. > > All non-trivial series, yeah. > > Maybe we should mention how v2 etc. of patch series should show what is > changed? If there is a good standard practice for that at all :-) > Dunno. I think that belongs primarily in the v2 0/n mail. It's not, after all, something that needs to be kept once the patches are applied. R. > > Segher >