linux/Documentation/process
Matthieu Baerts 0d828200ad docs: process: allow Closes tags with links
Since v6.3, checkpatch.pl now complains about the use of "Closes:" tags
followed by a link [1].  It also complains if a "Reported-by:" tag is
followed by a "Closes:" one [2].

As detailed in the first patch, this "Closes:" tag is used for a bit of
time, mainly by DRM and MPTCP subsystems.  It is used by some bug trackers
to automate the closure of issues when a patch is accepted.  It is even
planned to use this tag with bugzilla.kernel.org [3].

The first patch updates the documentation to explain what is this
"Closes:" tag and how/when to use it.  The second patch modifies
checkpatch.pl to stop complaining about it.

The DRM maintainers and their mailing list have been added in Cc as they
are probably interested by these two patches as well.

[1] https://lore.kernel.org/all/3b036087d80b8c0e07a46a1dbaaf4ad0d018f8d5.1674217480.git.linux@leemhuis.info/
[2] https://lore.kernel.org/all/bb5dfd55ea2026303ab2296f4a6df3da7dd64006.1674217480.git.linux@leemhuis.info/
[3] https://lore.kernel.org/linux-doc/20230315181205.f3av7h6owqzzw64p@meerkat.local/


This patch (of 5):

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 76f381bb77 ("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" should be used with any public bug
report.  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.  As suggested by Thorsten [6] again, if we follow the
same logic, the "Closes" tag should then be used after a "Reported-by"
one.

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://lkml.kernel.org/r/20230314-doc-checkpatch-closes-tag-v4-0-d26d1fa66f9f@tessares.net
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://lore.kernel.org/linux-doc/2194d19d-f195-1a1e-41fc-7827ae569351@leemhuis.info/ [6]
Link: https://github.com/multipath-tcp/mptcp_net-next/issues/373
Link: https://lkml.kernel.org/r/20230314-doc-checkpatch-closes-tag-v4-1-d26d1fa66f9f@tessares.net
Signed-off-by: Matthieu Baerts <matthieu.baerts@tessares.net>
Suggested-by: Thorsten Leemhuis <linux@leemhuis.info>
Acked-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Acked-by: Joe Perches <joe@perches.com>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: David Airlie <airlied@gmail.com>
Cc: Dwaipayan Ray <dwaipayanray1@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kai Wasserbäch <kai@dev.carbon-project.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
2023-04-18 16:39:31 -07:00
..
1.Intro.rst doc:it_IT: add some process/* translations 2018-11-20 09:11:12 -07:00
2.Process.rst Documentation: process: replace outdated LTS table w/ link 2022-10-24 11:27:01 -06:00
3.Early-stage.rst Documentation/process: use scripts/get_maintainer.pl on patches 2022-05-09 16:12:16 -06:00
4.Coding.rst doc: use KCFLAGS instead of EXTRA_CFLAGS to pass flags from command line 2021-02-22 13:59:10 -07:00
5.Posting.rst docs: process: allow Closes tags with links 2023-04-18 16:39:31 -07:00
6.Followthrough.rst
7.AdvancedTopics.rst Replace HTTP links with HTTPS ones: documentation 2020-06-08 09:30:19 -06:00
8.Conclusion.rst docs: process: remove outdated submitting-drivers.rst 2022-07-14 15:03:57 -06:00
adding-syscalls.rst docs: Make syscalls' helpers naming consistent 2021-02-04 14:47:24 -07:00
applying-patches.rst Documentation: describe how to apply incremental stable patches 2022-03-09 16:29:44 -07:00
botching-up-ioctls.rst doc: fix typo in botching up ioctls 2023-01-13 09:26:19 -07:00
changes.rst Documentation: raise minimum supported version of binutils to 2.25 2022-12-13 22:21:14 +09:00
clang-format.rst Documentation: fix typos found in process, dev-tools, and doc-guide subdirectories 2020-12-03 15:55:04 -07:00
code-of-conduct-interpretation.rst docs: update mediator contact information in CoC doc 2022-11-10 18:45:11 +01:00
code-of-conduct.rst Code of Conduct: Change the contact email address 2018-10-22 07:33:36 +01:00
coding-style.rst coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") 2022-09-29 13:20:53 -06:00
deprecated.rst docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage 2023-01-13 09:26:19 -07:00
development-process.rst
email-clients.rst Documentation: process: Document suitability of Proton Mail for kernel development 2023-01-13 09:26:19 -07:00
embargoed-hardware-issues.rst docs: embargoed-hardware-issues: add embargoed HW contact for Samsung 2023-01-27 10:04:06 +01:00
handling-regressions.rst docs: *-regressions.rst: explain how quickly issues should be handled 2022-02-24 12:57:25 -07:00
howto.rst Documentation/security-bugs: move from admin-guide/ to process/ 2023-03-12 15:56:43 +01:00
index.rst Documentation/security-bugs: move from admin-guide/ to process/ 2023-03-12 15:56:43 +01:00
kernel-docs.rst docs: Add book to process/kernel-docs.rst 2022-11-28 08:54:45 -07:00
kernel-driver-statement.rst doc:it_IT: add some process/* translations 2018-11-20 09:11:12 -07:00
kernel-enforcement-statement.rst Documentation: drop optional BOMs 2021-05-10 15:17:34 -06:00
license-rules.rst LICENSES: Rename other to deprecated 2019-05-03 06:34:32 -06:00
magic-number.rst Driver core changes for 6.1-rc1 2022-10-07 17:04:10 -07:00
maintainer-handbooks.rst docs: netdev: move the netdev-FAQ to the process pages 2022-03-31 10:49:39 +02:00
maintainer-netdev.rst docs: netdev: convert to a non-FAQ document 2022-12-28 10:06:06 +00:00
maintainer-pgp-guide.rst docs: maintainer-pgp-guide: update for latest gnupg defaults 2023-01-02 16:37:18 -07:00
maintainer-tip.rst x86/configs: Add x86 debugging Kconfig fragment plus docs 2022-04-06 19:56:29 +02:00
maintainers.rst doc-rst: Programmatically render MAINTAINERS into ReST 2019-10-02 10:03:17 -06:00
management-style.rst Documentation: management-style: Fix formatting of emphsized word 2020-03-10 11:32:34 -06:00
programming-language.rst docs: programming-language: add Rust programming language section 2023-03-07 10:24:40 -07:00
researcher-guidelines.rst Documentation/security-bugs: move from admin-guide/ to process/ 2023-03-12 15:56:43 +01:00
security-bugs.rst Documentation/security-bugs: move from admin-guide/ to process/ 2023-03-12 15:56:43 +01:00
stable-api-nonsense.rst doc: process: GPL -> GPL-compatible 2019-02-01 16:19:11 -07:00
stable-kernel-rules.rst Documentation/security-bugs: move from admin-guide/ to process/ 2023-03-12 15:56:43 +01:00
submit-checklist.rst doc: use KCFLAGS instead of EXTRA_CFLAGS to pass flags from command line 2021-02-22 13:59:10 -07:00
submitting-patches.rst docs: process: allow Closes tags with links 2023-04-18 16:39:31 -07:00
volatile-considered-harmful.rst Replace HTTP links with HTTPS ones: documentation 2020-06-08 09:30:19 -06:00