From patchwork Mon Jun 14 16:25:56 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 1491775 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=2620:52:3:1:0:246e:9693:128c; helo=sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha256 header.s=default header.b=cxy0Qedq; dkim-atps=neutral Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4G3cKP6vySz9sPf for ; Tue, 15 Jun 2021 02:26:48 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0AF863953CEC for ; Mon, 14 Jun 2021 16:26:46 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0AF863953CEC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1623688006; bh=OTdcrShWIZuzdsGOJd/bQHntSBK/+75EntjRWmJxfS8=; h=Date:To:Subject:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=cxy0Qedq4mel41bhBFeupkTrmoOOu0kHagS2TQwJ3tUz5iC+hR+p9mMeslTr6LmEL t0pW0T+m3MyTDISCxE/lwv2tw5gexZRBFbYaJUudpPNwNqO+KN2HbsS+KD5DWFNexy wBL6eHN+L/Ig6W/z31z0J/cUEDOTyaTzbl2b1GVY= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTP id 3B5CE3847806 for ; Mon, 14 Jun 2021 16:26:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 3B5CE3847806 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-528-7UcnaFK5PBO6BKukZ7Yptw-1; Mon, 14 Jun 2021 12:25:59 -0400 X-MC-Unique: 7UcnaFK5PBO6BKukZ7Yptw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 31115107ACF6; Mon, 14 Jun 2021 16:25:58 +0000 (UTC) Received: from localhost (unknown [10.33.36.175]) by smtp.corp.redhat.com (Postfix) with ESMTP id A5BA119D9B; Mon, 14 Jun 2021 16:25:57 +0000 (UTC) Date: Mon, 14 Jun 2021 17:25:56 +0100 To: gcc-patches@gcc.gnu.org Subject: [RFC] [wwwdocs] Rewrite docs on commit message and patch format Message-ID: MIME-Version: 1.0 X-Clacks-Overhead: GNU Terry Pratchett X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline X-Spam-Status: No, score=-13.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, 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-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Cc: Martin Sebor Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" I think this is an improvement on the current structure of the docs, but I'd like to hear what others think. We don't currently say document anything about commit format for the wwwdocs repo. Should the "wwwdocs" be a classifier (as in this email) or a component tag? commit 297dfc7049e5885de9ada2bf65235a13a74ff23e Author: Jonathan Wakely Date: Mon Jun 14 17:16:48 2021 +0100 Rewrite docs on commit message and patch format Move text about subject lines from contribute.html to codingconventions.html and then refer to it. Document DCO sign-off in commit message. diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html index 21cc95de..6c574a28 100644 --- a/htdocs/codingconventions.html +++ b/htdocs/codingconventions.html @@ -114,10 +114,12 @@ maintained and kept up to date. In particular:

ChangeLog entries are part of git commit messages and are automatically put -into a corresponding ChangeLog file. A ChangeLog template can be easily generated -with ./contrib/mklog.py script. GCC offers a checking script that -verifies a proper ChangeLog formatting (see git gcc-verify git alias). -for a particular git commit. The checking script covers most commonly used ChangeLog +into a corresponding ChangeLog file. +A ChangeLog template can be easily generated by the +./contrib/mklog.py script. GCC offers a checking script that +verifies proper ChangeLog formatting for a particular git commit +(see the git gcc-verify git alias). +The checking script covers most commonly used ChangeLog formats and the following paragraphs explain what it supports.

@@ -129,10 +131,12 @@ in comments rather than the ChangeLog, though a single line overall description of the changes may be useful above the ChangeLog entry for a large batch of changes.

-

Components

+

Components of a git commit message

    +
  • subject - a brief description of the commit
  • git_description - a leading text with git commit description
    • +
  • sign_off - DCO sign-off
  • committer_timestamp - line with timestamp and an author name and email (2 spaces before and after name)
    example: 2020-04-23␣␣Martin Liska␣␣<mliska@suse.cz>
  • additional_author - line with additional commit author name and email (starting with a tabular and 4 spaces)
    @@ -153,7 +157,9 @@ a large batch of changes.

    Format rules

      -
    • git_description - optional; ends right before one of the other compoments is found
      • +
    • subject - a single line in the format described below
      • +
    • git_description - optional; ends right before one of the other components is found
      • +
    • sign_off - optional; see DCO policy
    • committer_timestamp - optional; when found before a changelog_file, then it is added to each changelog entry
    • additional_author - optional
      • @@ -166,6 +172,65 @@ a large batch of changes.

    • co_authored_by - optional, can contain more than one
    +

    Subject line

    + +

    The first line of the commit message contains a brief summary that +encapsulates 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.

    + +Additionally, the subject should begin with a component tag, followed by +an optional series identifier. When related to one or more bugs, +it should end with the bug numbers. + +

    Ideally, the entire subject line should not exceed 75 characters.

    + +

    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 +commits in the series) and should be followed by a single dash surrounded +by white space.

    + +

    Bug number

    + +

    If your patch is related to 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) so that Bugzilla +will correctly notice the commit. +If your patch relates to two bugs, then write +[PRnnnnn, PRmmmmm]. +For more than two bugs just cite the most relevant one in the summary +and use an ellipsis after the first one; list all the +related PRs in the body of the commit message in the full form.

    + +

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

    +

    Documented behaviour

      @@ -182,7 +247,9 @@ a large batch of changes.

      Example patch

      -
      This patch adds a second movk pattern that models the instruction
+
      aarch64: Add an extra sbfiz pattern [PR87763]
+
+This patch adds a second movk pattern that models the instruction
 as a "normal" and/ior operation rather than an insertion.  It fixes
 the third insv_1.c failure in PR87763, which was a regression from
 GCC 8.
@@ -205,7 +272,11 @@ Co-Authored-By: Jack Bar  <jack@example.com>
 
      Tokenized patch
      
 
 
      -$git_description
+$subject
+
+$git_description
+
+$sign_off
 
 $committer_timestamp
 
diff --git a/htdocs/contribute.html b/htdocs/contribute.html
index c0cce359..b879b2d5 100644
--- a/htdocs/contribute.html
+++ b/htdocs/contribute.html
@@ -243,29 +243,17 @@ 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.
      
+the commit message for your patch, so should follow the same
+format,
+prefixed by a classifier.
      
 
 
      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 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 surrounded with square brackets,
+and is often written all upper case.  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:
      
 
@@ -275,61 +263,9 @@ a series marker (N/M).  Examples are:
      
   
    • [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:
      • +
    • [committed] - a patch that has already been committed.
    -

    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 @@ -362,7 +298,7 @@ original thread indicating that a new version has been submitted.

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

      -
    • [COMMITTED] libstdc++: Fix freestanding build [PR92376]
      • +
    • [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