[PATCH v2 1/2] docs: process: allow Closes tags with links

[Thorsten Leemhuis]

On 24.03.23 19:52, Matthieu Baerts wrote:
> 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.
> 
> [...]
> 
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index 7a670a075ab6..20f0b6b639b7 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'.
>  
> +Similarly, there is also the "Closes:" tag that can be used to close issues
> +when the underlying public bug tracker can do this operation automatically.
> +For example::
> +
> +	Closes: https://example.com/issues/1234
> +
> +Private bug trackers and invalid URLs are forbidden. For other public bug
> +trackers not supporting automations, keep using the "Link:" tag instead.
> [...]

This more and more seems half-hearted to me.

One reason: it makes things unnecessarily complicated for developers, as
they'd then have to remember `is this a public bug tracker that is
supporting automations? Then use "Closes", otherwise "Link:"`.

Another reason: the resulting situation ignores my regression tracking
bot, which (among others) tracks emailed reports. It would benefit from
"Closes" as well to avoid the ambiguity problem Konstantin brought up
(the one about "Link: might just point to a report for background
information in patches that don't address the problem the link points
to"[1]. But FWIW, I'm not sure if this ambiguity is much of a problem in
practice, I have a feeling that it's rare and most of the time will
happen after the reported problem has been addressed or in the same
patch-set.

I thus think we should use either of these approaches:

* just stick to "Link: <url>"

* go "all-in" and tell developers to use "Closes: <url>"[2] all the time
when a patch is resolving an issue that was reported in public

I'm not sure which of them I prefer myself. Maybe I'm slightly leaning
towards the latter: it avoids the ambiguity, checkpatch.pl will yell if
it's used with something else than a URL, it makes things easier for
MPTCP & DRM developers, and (maybe most importantly) is something new
developers are often used to already from git forges.

Ciao, Thorsten

[1]
https://lore.kernel.org/linux-doc/20230317185637.ebxzsdxivhgzkqqw@meerkat.local/

[2] fwiw, I still prefer "Resolves:" over "Closes". Yes, I've seen
Konstantin's comment on the subtle difference between the two[3], but as
he said, Bugbot can work with it as well. But to me "Resolves" sounds
way friendlier and more descriptive to me; but well, I'm not a native
speaker, so I don't think my option should count much here.

[3]
https://lore.kernel.org/linux-doc/20230316162227.727rhima2tejdl5j@meerkat.local/