On Mon, 16 Dec 2019, Russell King - ARM Linux admin <linux@xxxxxxxxxxxxxxx> wrote: > On Mon, Dec 16, 2019 at 04:02:04PM +0200, Jani Nikula wrote: >> On Mon, 16 Dec 2019, Russell King - ARM Linux admin <linux@xxxxxxxxxxxxxxx> wrote: >> > On Mon, Dec 16, 2019 at 03:14:56PM +0200, Jani Nikula wrote: >> >> On Mon, 16 Dec 2019, Linus Walleij <linus.walleij@xxxxxxxxxx> wrote: >> >> > We have a lot of Link: tags in commits these days and they are >> >> > not formally defined in the kernel documentation. Let's put >> >> > a separate paragraph about it in submitting-patches.rst where >> >> > most other tags are defined. >> >> > >> >> > Cc: Jonathan Corbet <corbet@xxxxxxx> >> >> > Cc: Russell King <linux@xxxxxxxxxxxxxxx> >> >> > Reported-by: Russell King <linux@xxxxxxxxxxxxxxx> >> >> > Signed-off-by: Linus Walleij <linus.walleij@xxxxxxxxxx> >> >> > --- >> >> > Documentation/process/submitting-patches.rst | 21 ++++++++++++++++---- >> >> > 1 file changed, 17 insertions(+), 4 deletions(-) >> >> > >> >> > diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst >> >> > index ba5e944c7a63..20ef984aa743 100644 >> >> > --- a/Documentation/process/submitting-patches.rst >> >> > +++ b/Documentation/process/submitting-patches.rst >> >> > @@ -643,9 +643,22 @@ which stable kernel versions should receive your fix. This is the preferred >> >> > method for indicating a bug fixed by the patch. See :ref:`describe_changes` >> >> > for more details. >> >> > >> >> > +14) Link: tags >> >> > +-------------- >> >> > + >> >> > +A Link: attribute can be used to provide a link back to a protocol of a >> >> > +discussion pertaining to the patch. A typical link looks like this: >> >> > + >> >> > + Link: https://lore.kernel.org/r/<message-id> >> >> > + >> >> > +Any HTTP[S] links can be referenced. It is customary for maintainers to add >> >> > +Link: tags to reference discussions on mailing lists, and this can be done >> >> > +automatically with the git tool when applying patches in mailbox format, see >> >> > +:ref:`Documentation/maintainer/configure-git.rst <configure git>`. >> >> >> >> I'd like to emphasize even more strongly that it is applied by the >> >> maintainer or committer, and should reference the patch that got >> >> applied. And that the patch submitters shouldn't try to add it >> >> themselves. (Which makes you wonder about the placement in >> >> submitting-patches.rst.) IMO other references should use References: >> >> that is already widely used. >> > >> > I'm the maintainer of phylink. During discussions, I may propose a >> > patch for someone to try. When successful, I'll send a new email >> > submitting the patch officially to davem as the networking maintainer >> > as an entirely separate thread. >> > >> > Using Link: to the patch that was submitted officially is obviously >> > impossible, but you would want to link to the discussion that resulted >> > in the patch, rather than the official submission - which would >> > generally be the submission plus an "applied" reply. >> >> If there are N versions of the patch with discussion that eventually >> lead to the final version that was applied, which one of the previous >> patch versions or discussions do you think should be linked to? IMO the >> only one that actually is unambiguous is the patch that got applied. IMO >> only patches that were submitted to a mailing list should be applied. > > Even if it's just the patch submission and an "applied" reply. To me, > that seems to be just noise. > > My point with the above scenario is that the discussion that resulted > in the patch being proposed is the relevant discussion that needs to > be linked to the patch - which will include the context about why the > patch was generated and its testing. The official submission will > contain none of that. > > I guess what this is highlighting is that different people have > different ways of working, and trying to force one thing (Link:) to > be used with one way of working doesn't scale across the whole kernel. > > So, stating that Link: should only be added by a maintainer or > committer will have a detrimental effect on workflows that do not > match the one you have in mind. Basically this boils down to the question whether it is generally more useful to have a Link: tag with a very specific meaning and potentially *other* less specific additional tags for other purposes, or to not define a specific meaning to the Link: tag at all. I promote the former, with e.g. References: used for more free form references. I'm really fine with either, but with the latter I'll just filter out submitter added Link: tags and turn them to References: or something in my corner of the kernel. (Meaning that lax Link: tags will have a detrimental effect on workflows that do not match the one you have in mind... ;) BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center
