lkml.org 
[lkml]   [2023]   [Mar]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Date
    Subject[PATCH 1/2] docs: process: allow Closes tags with links
    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] and GitHub [2] when the appropriated tag is
    used. They both 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 [3].

    checkpatch.pl script should then stop complaining about this "Closes"
    tag. As suggested by Thorsten [4], if this tag is accepted, it should
    first be described in the documentation. This is what is done here in
    this patch.

    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.

    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/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [3]
    Link: https://lore.kernel.org/all/688cd6cb-90ab-6834-a6f5-97080e39ca8e@leemhuis.info/ [4]
    Link: https://github.com/multipath-tcp/mptcp_net-next/issues/373
    Suggested-by: Thorsten Leemhuis <linux@leemhuis.info>
    Signed-off-by: Matthieu Baerts <matthieu.baerts@tessares.net>
    ---
    Documentation/process/5.Posting.rst | 9 +++++++++
    Documentation/process/submitting-patches.rst | 7 +++++++
    2 files changed, 16 insertions(+)

    diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
    index 7a670a075ab6..582d67eb2420 100644
    --- a/Documentation/process/5.Posting.rst
    +++ b/Documentation/process/5.Posting.rst
    @@ -217,6 +217,15 @@ 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'.

    +In the same category as linking web pages, a special tag is also used to close
    +issues but only when the mentioned ticketing system can do this operation
    +automatically::
    +
    + Closes: https://example.com/issues/1234
    +
    +Please use this 'Closes:' tag only if it helps managing issues thanks to
    +automations. If not, pick the 'Link:' one.
    +
    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..88561a32b5cc 100644
    --- a/Documentation/process/submitting-patches.rst
    +++ b/Documentation/process/submitting-patches.rst
    @@ -134,6 +134,13 @@ 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.

    +Note that it might be interesting to use the 'Closes:' tag instead of 'Link:'
    +if the URL points to an issue from public bug tracker that can automatically
    +close tickets when such patches containing this tag is accepted upstream. For
    +example::
    +
    + Closes: https://example.com/issues/1234
    +
    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
    --
    2.39.2

    \
     
     \ /
      Last update: 2023-03-27 01:01    [W:6.942 / U:0.012 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site