From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ot1-x32d.google.com (mail-ot1-x32d.google.com [IPv6:2607:f8b0:4864:20::32d]) by sourceware.org (Postfix) with ESMTPS id 26EA33857420 for ; Tue, 15 Jun 2021 17:37:39 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 26EA33857420 Received: by mail-ot1-x32d.google.com with SMTP id o17-20020a9d76510000b02903eabfc221a9so15131676otl.0 for ; Tue, 15 Jun 2021 10:37:39 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=clPQLFlpXlDLH2Hqg8OWioUntuZbKrEd+DcCxjgLZR0=; b=fkyffxqsyw1tTjUCPl3qoCluqA3GhSFJcNPq+SD8O/twelv9efIibEYlbP7Fth0B7X yN4IA//HHDMTUEh/khIHA2yoPqNMzwLg6jMLW3U/t4sJdsqGlcWNJ1Fs9i4DuP0pksk1 p1VtxSsIJ4BdbB7oO6R3jTz+XkIJn2HwDpx0nj9xC4hZPnA9yhSMPXN4CYazVq/7sSB6 ygLgI04vJoS5ONv0ok7tE+z4kl9OuLgGCBF8MsVCKVyxoS97gErOpKVgxWnprQpyAAtS zeLmh5r0aEKngapqr2PKPAWgrFQfBBGxlAX10WMaunoV/8kuDrhqKsqbjVuyQoHjSaH9 15UQ== X-Gm-Message-State: AOAM5337mKrFs9ftGTyl2yB65/yOZ9rzGG43CZrguFM+WuGhJRq+cQYw NslqBtsAKEb7Zj5RUf59tEQ= X-Google-Smtp-Source: ABdhPJx/sgPX4A8jeQR4GvQpwzzWxMqpGpSp+paMDbhrpC6mptOMDPL4RzRzBSChNZLfpuoKxpLEzQ== X-Received: by 2002:a05:6830:1191:: with SMTP id u17mr326807otq.43.1623778658397; Tue, 15 Jun 2021 10:37:38 -0700 (PDT) Received: from [192.168.0.41] (97-118-105-195.hlrn.qwest.net. [97.118.105.195]) by smtp.gmail.com with ESMTPSA id x31sm4103648ota.24.2021.06.15.10.37.37 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 15 Jun 2021 10:37:38 -0700 (PDT) Subject: Re: [RFC] [wwwdocs] Rewrite docs on commit message and patch format To: Jonathan Wakely Cc: gcc Patches , Martin Sebor References: <858882ae-9a19-51b7-531c-d2be4bc303c7@gmail.com> From: Martin Sebor Message-ID: Date: Tue, 15 Jun 2021 11:37:37 -0600 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.2 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-3.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 15 Jun 2021 17:37:40 -0000 On 6/15/21 3:39 AM, Jonathan Wakely wrote: > On Tue, 15 Jun 2021 at 01:12, Martin Sebor wrote: >> >> On 6/14/21 10:25 AM, Jonathan Wakely via Gcc-patches wrote: >>> I think this is an improvement on the current structure of the docs, >>> but I'd like to hear what others think. >> >> The text looks more detailed and arguably more accurate but also >> makes it sound more complicated and rigid than necessary. It >> also doesn't look like the commit hook tries to enforce many of >> these elements. If it did, quite a number of commits would fail. >> >> So I'm not sure about the value of documenting expectations that >> only few commits would meet. > > We don't have to be too strict, but encouraging good practice still > makes the commit logs more useful. Even if only 50% of commit follow > it, that still seems to make the logs easier to skim than if there is > no consistency at all. > >> E.g., including the Component tag, >> or putting PRnnnnn at the end of the Subject line with no space >> (why ask for no space and not, for example PR #nnnnn?) In fact, > > That was always there, I just moved it from one page to another. I > have traditionally used a space before the bug number, so I'm fine > with that format, but I don't really think it makes the docs better to > list too many variations. And I am not trying to make big changes to > the policy with this patch, just reorganize the existing docs to > reflect the modern workflow (i.e. Git commits with automatically > generated ChangeLog files, rather than everything being about the > ChangeLog). > >> unless we mean it (and are willing to enforce it) I think it >> would be best to either leave it out completely, or make it clear >> that it's not required. > > If we don't enforce it, then it's not required. Commits that don't do > it will still get in. > > I think suggesting a single format (but allowing variations on it) is > **much** better than not saying anything at all. For new contributors > it's helpful to say "this is what we want" so they have a guideline to > follow. > > My revised patch sent a few minutes ago adds: > >

A major benefit of a good, descriptive subject line is that it makes > the output of git log --oneline more useful. Including the > component tag and bug number(s) helps with that, but isn't compulsory > if the subject is already clear and has enough context.

> > Does that make you happier? I expect most users to read this text either before they commit their first GCC change or after the commit hook rejects it. At that point, what they'll want to find out as quickly and effortlessly as possible, is what they need to do to get the patch committed without an error. Reading several paragraphs of best practices isn't likely to be the most expedient way to figure that out. What it will be is frustrating, especially if the hard requirements are sprinkled among but not obviously distinguished from the best practices, and if following some but not others doesn't resolve the error. To minimize the frustration I'd suggest to identify the hard requirements and add links showing examples of representative commits that follow the best practices. Then the rest of the text can go over all the details of classifiers and component tags, etc., with more links to example commits. As an aside, adopting the same conventions across all toolchain projects (Binutils/GDB, GCC, and Glibc) would simplify things for contributors to all of them. Martin PS To the point of pulling up git log and using the last commit as a template: that works but unless the last commit follows the best practices it doesn't accomplish what you want.