From patchwork Thu Mar 30 18:13:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Matthieu Baerts X-Patchwork-Id: 77356 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp52004vqo; Thu, 30 Mar 2023 11:25:21 -0700 (PDT) X-Google-Smtp-Source: AKy350ZE4snqw7ghYs6ZIHbbwN8v64+qBrmVwxtXH2x3aGoA49pavxb7WJNzy9KMvx987+4Gy0ix X-Received: by 2002:a17:90b:4a45:b0:23d:1fc0:dd1f with SMTP id lb5-20020a17090b4a4500b0023d1fc0dd1fmr24838429pjb.38.1680200720931; Thu, 30 Mar 2023 11:25:20 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1680200720; cv=none; d=google.com; s=arc-20160816; b=QXaigOAWVSuxjsi+Zyd9aDZFa6yZsdaEZo1paVuczj2eaP0PUN3lQH8BH6RUbNf0+O JPU8rdU5ToA8A2pjYrgLsZx4vFGrBNP2gvQIGxlukwudWkf4ByjfnGgFnJF9GPCW1MCw tJNFsGsujM3ADkMTl6GDxDJg2MNk48AqpF23U5ukI9ARbksI+nNpc5NNeGgnAEElaxNl lVdesT81G32duXJPM0TmOOYn99J4PxV6vq/2th1iGqymCL/Qha/3yChIo6n3+EBOtAJm xCN60ZTmW3wuzW0hYvPTmzfwEQjL5ZrkV+BC9Qucfpw0uOA1Ts4FITfz/GC6W2Rs6kqy ADMA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:in-reply-to:references:message-id :content-transfer-encoding:mime-version:subject:date:from :dkim-signature; bh=ItInTAdnUAKLm+cm48IAJm3RPistuWUxFPvzsYYlPp8=; b=gZetmr+lOcacU03h9tn6wQrOjgFdZBE2x5tM8iZkbAYVR7ZUXVBg1ISoTwf5fMidOs OBJPAWZnlo9uAEh5/OlLx8h/16GC+W1WbtEKXt6GE25LGnNOFYP5af9Mvlebbu+RkA32 UZWvG96vurogkFILmfRNgcdqEPiB/cCHo0Hf1qMTs8Uq+qmMpmp8i/0rfWGuN8ofWWu1 6obSanJYDgJ2uOUDv5xBfiKdMe0NJTUcfQ2zFTTK8KYqO7tOnoIckMgz7tLb+MgnjSFi 6wVxJmaOU4HmccWHF2/yb+tS43tHZ5vwDcoRAfzsAGYm+VizuzhopAvGPltESsklet7p Lvxw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@tessares.net header.s=google header.b=oAoL62t7; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=tessares.net Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id c2-20020a170902724200b001a0ae87878dsi92406pll.388.2023.03.30.11.25.07; Thu, 30 Mar 2023 11:25:20 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@tessares.net header.s=google header.b=oAoL62t7; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=tessares.net Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230183AbjC3SNv (ORCPT + 99 others); Thu, 30 Mar 2023 14:13:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44440 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229839AbjC3SNs (ORCPT ); Thu, 30 Mar 2023 14:13:48 -0400 Received: from mail-wr1-x435.google.com (mail-wr1-x435.google.com [IPv6:2a00:1450:4864:20::435]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A94E2E18C for ; Thu, 30 Mar 2023 11:13:46 -0700 (PDT) Received: by mail-wr1-x435.google.com with SMTP id e18so19989944wra.9 for ; Thu, 30 Mar 2023 11:13:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tessares.net; s=google; t=1680200025; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=ItInTAdnUAKLm+cm48IAJm3RPistuWUxFPvzsYYlPp8=; b=oAoL62t7ERceub5TArLZ0xHe2p0ee4pBYyiAIEOnsb8ui0gahY61b5IZaCieOHj209 Jt8BFb2IIz5n1Q9I1ivzz0o/vULmPNWs9hXFwX0fWsAu+lwjuWxgTwapVPvI3bffYMfW pQ+eneHIxILNbXo7+sRI6WPXcIcsczDyxv7sw9P7+yaD/vlDFrKxfynWWPjPX3ZOW6EQ VQWD1m1VrZ4xTS8GOhlWtJ4TwCYuHe4Gnza6xlRoPu+qmx8nSN81FRD+y1eOjU8b0SE+ c6xsUUWt7QfGDTBIz43ahfu8ssU0xaERzizLu4h5pnclgf5mThDiU5nIlTkMaCx4T6pp UBBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1680200025; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=ItInTAdnUAKLm+cm48IAJm3RPistuWUxFPvzsYYlPp8=; b=uZqc1iur06YpzYWoLmhnaJrcTsgoi1Ng15RERm8ZP74fa+96oeV+aXqCS0Yd6EKgMJ Ol//DCuf3BK3+MuCkZH5Fum0p7adTo3ySSQWkSOd4w12a/m6byl0b8asLd6AIBMAqDoD YdbL8R5oa2sYSuyPikLXY46upctkvK54SSgUGaUwrKsPzMjnlE5xYn61fcFGgQopHQnk AxyotcLitKJlQWOam3QkwCVeU864EoROzTkB0/sdm4ipA2Lth/vGrh32yGm9o3z9smTx lOp1BuiqRXCn9ObEjkDiNAonEHBzAdHQO5kQDn0/Jeao6rlXvZq1fNx3bjoiKGin1RJI tOqw== X-Gm-Message-State: AAQBX9ekd2WRgkmc93G2XTur+NoC/BcnfBRmZj1FZwLataHy8FGixM6N 9JG9wr1+p/svYv8TWuw7V70RMQ== X-Received: by 2002:a5d:68cb:0:b0:2cf:fd6:b83f with SMTP id p11-20020a5d68cb000000b002cf0fd6b83fmr4895020wrw.8.1680200024971; Thu, 30 Mar 2023 11:13:44 -0700 (PDT) Received: from vdi08.nix.tessares.net (static.219.156.76.144.clients.your-server.de. [144.76.156.219]) by smtp.gmail.com with ESMTPSA id e18-20020a056000121200b002d24a188b64sm33459741wrx.112.2023.03.30.11.13.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Mar 2023 11:13:44 -0700 (PDT) From: Matthieu Baerts Date: Thu, 30 Mar 2023 20:13:23 +0200 Subject: [PATCH v3 1/4] docs: process: allow Closes tags with links MIME-Version: 1.0 Message-Id: <20230314-doc-checkpatch-closes-tag-v3-1-d1bdcf31c71c@tessares.net> References: <20230314-doc-checkpatch-closes-tag-v3-0-d1bdcf31c71c@tessares.net> In-Reply-To: <20230314-doc-checkpatch-closes-tag-v3-0-d1bdcf31c71c@tessares.net> To: Jonathan Corbet , Andy Whitcroft , Joe Perches , Dwaipayan Ray , Lukas Bulwahn , =?utf-8?q?Kai_Wasserb=C3=A4ch?= , Thorsten Leemhuis , Andrew Morton , David Airlie , Daniel Vetter , Konstantin Ryabitsev , Bagas Sanjaya , Linus Torvalds Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, mptcp@lists.linux.dev, Matthieu Baerts X-Mailer: b4 0.12.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=6878; i=matthieu.baerts@tessares.net; h=from:subject:message-id; bh=tCxJpCXZj/WPjBCToCpp+PIvuovD/Z8f6431psypKfg=; b=owEBbQKS/ZANAwAIAfa3gk9CaaBzAcsmYgBkJdFWi0sLZAteAQ7quTCDXY0wVDMKo9SHHZpFH reIJgAmbMqJAjMEAAEIAB0WIQToy4X3aHcFem4n93r2t4JPQmmgcwUCZCXRVgAKCRD2t4JPQmmg c7nlD/wI1UTBtopo8m/HSsTHXh/OShmdMF9UeXrWgwgn1Ch24A6x6JUw5L7qcDEJDH9fiZk4z3g CExEzis51ESVDfUaBoIF1F+UN/WjG6Ol8Ntx7Q0w+yTwclRLgR5CKF93jZvS064JKUfMo6kyZkw cXJW4kkM0net/5DicixSKupjHETn6eicuPFMe6/dww51hX+98+9KKZSHs7K0miiLZ7ZvZC+a5FS XfNXGPPvKmd0PIABR7+nLZ2lonL7EHnIseTdU2rN5PR5XpdXLABGsRtPZ/mSuipaQs5TxuJLLAb kbZ4bTkhIZoab5AWF6Vl6R5eLB2qhr61RqO5UmAqg2ck1Jk/fU5GzJM8morO/zlBTSVMQJP+iP/ r6e4Ii9QggrM/rSUnhmEbgSJFMRJJJDQJKGzB6PL1yrG9HZkobh+vivcBtH9CedfLwkGV4o+doo zOxGIPWNIZ3p6HHiw4dh7fQnWwkfTST7aEGMO1d3vkADk9rouoaUw6x9KnTX79H/Yeq67Q24fK2 N1nJjnL0a2R7hFnAqSepLv1F888I4t8YbiboUUZ54X5YGZvdgMBpRnxYg2bzvdXRD7I3XE7vMht OdFJkLe+Pt6f2+0dSv8fw+Ykz4zQH7ZP6s+9QVOs6K4oHMpaXiSnmI/+Rk27rC5ipHdWY52bDs2 wgxUqnuCJN1hJFg== X-Developer-Key: i=matthieu.baerts@tessares.net; a=openpgp; fpr=E8CB85F76877057A6E27F77AF6B7824F4269A073 X-Spam-Status: No, score=-0.2 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1761818151197031061?= X-GMAIL-MSGID: =?utf-8?q?1761818151197031061?= Making sure a bug tracker is up to date is not an easy task. For example, a first version of a patch fixing a tracked issue can be sent a long time after having created the issue. But also, it can take some time to have this patch accepted upstream in its final form. When it is done, someone -- probably not the person who accepted the patch -- has to remember about closing the corresponding issue. This task of closing and tracking the patch can be done automatically by bug trackers like GitLab [1], GitHub [2] and hopefully soon [3] bugzilla.kernel.org when the appropriated tag is used. The two first ones accept multiple tags but it is probably better to pick one. According to commit 76f381bb77a0 ("checkpatch: warn when unknown tags are used for links"), the "Closes" tag seems to have been used in the past by a few people and it is supported by popular bug trackers. Here is how it has been used in the past: $ git log --no-merges --format=email -P --grep='^Closes: http' | \ grep '^Closes: http' | cut -d/ -f3-5 | sort | uniq -c | sort -rn 391 gitlab.freedesktop.org/drm/intel 79 github.com/multipath-tcp/mptcp_net-next 8 gitlab.freedesktop.org/drm/msm 3 gitlab.freedesktop.org/drm/amd 2 gitlab.freedesktop.org/mesa/mesa 1 patchwork.freedesktop.org/series/73320 1 gitlab.freedesktop.org/lima/linux 1 gitlab.freedesktop.org/drm/nouveau 1 github.com/ClangBuiltLinux/linux 1 bugzilla.netfilter.org/show_bug.cgi?id=1579 1 bugzilla.netfilter.org/show_bug.cgi?id=1543 1 bugzilla.netfilter.org/show_bug.cgi?id=1436 1 bugzilla.netfilter.org/show_bug.cgi?id=1427 1 bugs.debian.org/625804 Likely here, the "Closes" tag was only properly used with GitLab and GitHub. We can also see that it has been used quite a few times (and still used recently) and this is then not a "random tag that makes no sense" like it was the case with "BugLink" recently [4]. It has also been misused but that was a long time ago, when it was common to use many different random tags. checkpatch.pl script should then stop complaining about this "Closes" tag. As suggested by Thorsten [5], if this tag is accepted, it should first be described in the documentation. This is what is done here in this patch. To avoid confusion, the "Closes" can be used with any public links. No need to check if the underlying bug tracker supports automations. Having this tag with any kind of public bug reports allows bots like regzbot to clearly identify patches fixing a specific bug and avoid false-positives, e.g. patches mentioning it is related to an issue but not fixing it. Note that thanks to this "Closes" tag, the mentioned bug trackers can also locate where a patch has been applied in different branches and repositories. If only the "Link" tag is used, the tracking can also be done but the ticket will not be closed and a manual operation will be needed. Also, these bug trackers have some safeguards: the closure is only done if a commit having the "Closes:" tag is applied in a specific branch. It will then not be closed if a random commit having the same tag is published elsewhere. Also in case of closure, a notification is sent to the owners. Link: https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern [1] Link: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests [2] Link: https://lore.kernel.org/linux-doc/20230315181205.f3av7h6owqzzw64p@meerkat.local/ [3] Link: https://lore.kernel.org/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [4] Link: https://lore.kernel.org/all/688cd6cb-90ab-6834-a6f5-97080e39ca8e@leemhuis.info/ [5] Link: https://github.com/multipath-tcp/mptcp_net-next/issues/373 Suggested-by: Thorsten Leemhuis Acked-by: Konstantin Ryabitsev Signed-off-by: Matthieu Baerts --- v3: - Allow using the "Closes" tag with any bug reports, not only the ones supporting automations, useful for regzbot, etc. (Thorsten Leemhuis) v2: - Add Konstantin's Acked-by: even if the patch has changed a bit, the concept is still the same, I hope that's OK. - Mention "public" in "5.Posting.rst" file as well. (Jonathan Corbet) - Re-phrase the new text from "5.Posting.rst". (Bagas Sanjaya & Thorsten Leemhuis) - Clearly mention that private bug trackers and invalid URLs are forbidden (Linus Torvalds). --- Documentation/process/5.Posting.rst | 10 ++++++++++ Documentation/process/submitting-patches.rst | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 7a670a075ab6..c755ca795f15 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -217,6 +217,16 @@ latest public review posting of the patch; often this is automatically done by tools like b4 or a git hook like the one described in 'Documentation/maintainer/configure-git.rst'. +Similarly, there is also the "Closes:" tag that can be used to mark any +kind of public bug report as closed. For example:: + + Closes: https://example.com/issues/1234 + +Some bug trackers have the ability to close issues automatically when a +commit with such a tag is applied. Some bots monitoring mailing lists can +also track such tags and take certain actions. Private bug trackers and +invalid URLs are forbidden. + A third kind of tag is used to document who was involved in the development of the patch. Each of these uses this format:: diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 69ce64e03c70..b0ea03f18bad 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -134,6 +134,16 @@ resources. In addition to giving a URL to a mailing list archive or bug, summarize the relevant points of the discussion that led to the patch as submitted. +It might be interesting to use the 'Closes:' tag to mark any kind of public +bug report as closed. For example:: + + Closes: https://example.com/issues/1234 + +Some bug trackers have the ability to close issues automatically when a +commit with such a tag is applied. Some bots monitoring mailing lists can +also track such tags and take certain actions. Private bug trackers and +invalid URLs are forbidden. + If your patch fixes a bug in a specific commit, e.g. you found an issue using ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of the SHA-1 ID, and the one line summary. Do not split the tag across multiple