[PATCH] Documentation: add Internal-reference-ID: patch tag

[PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

From: Randy Dunlap <rdunlap@xenotime.net>

Introduce "Internal-reference-ID:" for company-internal
patch tracking.  Also clarify that URLs in patches should be
public, not private.

Based on emails from Greg Kroah-Hartman.

Internal-reference-ID: rdunlap.2011.0729.id1

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Cc: Mike Waychison <mikew@google.com>
Cc: Greg Kroah-Hartman <gregkh@suse.de>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Theodore Tso <tytso@MIT.EDU>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
---
 Documentation/SubmittingPatches |   25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

--- linux-3.0-git11.orig/Documentation/SubmittingPatches
+++ linux-3.0-git11/Documentation/SubmittingPatches
@@ -108,7 +108,14 @@ This benefits both the patch merger(s) a
 probably didn't even receive earlier versions of the patch.
 
 If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.
+number and URL (for URLs that are public, i.e., available to
+everyone).
+
+Please don't include private (internal) URLs in patch descriptions,
+so just say something like:
+	Fixes fubar.com bugzilla #4311
+instead of
+	Fixes bugzilla.fubar.com/show_bug.cgi?id=4311
 
 
 3) Separate your changes.
@@ -469,7 +476,19 @@ understand the subject area and to perfo
 increase the likelihood of your patch getting into the kernel.
 
 
-15) The canonical patch format
+15) Internal-reference-ID: tag
+
+Sometimes a company wants to include an internal reference ID (tag)
+in a patch so that they can have better patch tracking.  Instead of
+having a bazillion different such ID tags, the accepted one for
+everyone to use is:
+
+Internal-reference-ID: <text>
+
+<text> should not be a private (internal) URL.
+
+
+16) The canonical patch format
 
 The canonical patch subject line is:
 
@@ -583,7 +602,7 @@ See more details on the proper patch for
 references.
 
 
-16) Sending "git pull" requests  (from Linus emails)
+17) Sending "git pull" requests  (from Linus emails)
 
 Please write the git repo address and branch name alone on the same line
 so that I can't even by mistake pull from the wrong branch, and so

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Greg KH]

On Fri, Jul 29, 2011 at 06:00:28PM -0700, Randy Dunlap wrote:
> From: Randy Dunlap <rdunlap@xenotime.net>
> 
> Introduce "Internal-reference-ID:" for company-internal
> patch tracking.  Also clarify that URLs in patches should be
> public, not private.
> 
> Based on emails from Greg Kroah-Hartman.
> 
> Internal-reference-ID: rdunlap.2011.0729.id1
> 
> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> Cc: Mike Waychison <mikew@google.com>
> Cc: Greg Kroah-Hartman <gregkh@suse.de>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: "H. Peter Anvin" <hpa@zytor.com>
> Cc: Theodore Tso <tytso@MIT.EDU>
> Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>

Acked-by: Greg Kroah-Hartman <gregkh@suse.de>

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Mike Waychison]

On Sat, Jul 30, 2011 at 4:56 PM, Greg KH <gregkh@suse.de> wrote:
> On Fri, Jul 29, 2011 at 06:00:28PM -0700, Randy Dunlap wrote:
>> From: Randy Dunlap <rdunlap@xenotime.net>
>>
>> Introduce "Internal-reference-ID:" for company-internal
>> patch tracking.  Also clarify that URLs in patches should be
>> public, not private.
>>
>> Based on emails from Greg Kroah-Hartman.
>>
>> Internal-reference-ID: rdunlap.2011.0729.id1
>>
>> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
>> Cc: Mike Waychison <mikew@google.com>
>> Cc: Greg Kroah-Hartman <gregkh@suse.de>
>> Cc: Andrew Morton <akpm@linux-foundation.org>
>> Cc: "H. Peter Anvin" <hpa@zytor.com>
>> Cc: Theodore Tso <tytso@MIT.EDU>
>> Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
>
> Acked-by: Greg Kroah-Hartman <gregkh@suse.de>
>

Acked-by: Mike Waychison <mikew@google.com>

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

On 07/31/2011 11:07 AM, Mike Waychison wrote:
>>>
>>> Internal-reference-ID: rdunlap.2011.0729.id1
>>>
> 
> Acked-by: Mike Waychison <mikew@google.com>
> 

Just to avoid namespace collisions, can we at least put the owner
somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google> and
so on?

	-hpa

-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

On Sun, 31 Jul 2011 11:09:56 -0700 H. Peter Anvin wrote:

> On 07/31/2011 11:07 AM, Mike Waychison wrote:
> >>>
> >>> Internal-reference-ID: rdunlap.2011.0729.id1
> >>>
> > 
> > Acked-by: Mike Waychison <mikew@google.com>
> > 
> 
> Just to avoid namespace collisions, can we at least put the owner
> somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google> and
> so on?

I would prefer to leave the text contents as unspecified, but I wouldn't
mind recommending that users try to make them unique, e.g., by using
a company-ID or owner-ID.  Would that be acceptable?


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

Randy Dunlap <rdunlap@xenotime.net> wrote:

>On Sun, 31 Jul 2011 11:09:56 -0700 H. Peter Anvin wrote:
>
>> On 07/31/2011 11:07 AM, Mike Waychison wrote:
>> >>>
>> >>> Internal-reference-ID: rdunlap.2011.0729.id1
>> >>>
>> > 
>> > Acked-by: Mike Waychison <mikew@google.com>
>> > 
>> 
>> Just to avoid namespace collisions, can we at least put the owner
>> somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google>
>and
>> so on?
>
>I would prefer to leave the text contents as unspecified, but I
>wouldn't
>mind recommending that users try to make them unique, e.g., by using
>a company-ID or owner-ID.  Would that be acceptable?
>
>
>---
>~Randy
>*** Remember to use Documentation/SubmitChecklist when testing your
>code ***

No, that wouldn't work when there is more than one tag from different users.  And yes, I fully expect to see that.
-- 
Sent from my mobile phone. Please excuse my brevity and lack of formatting.

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

On Sat, 13 Aug 2011 17:29:52 -0400 H. Peter Anvin wrote:

> Randy Dunlap <rdunlap@xenotime.net> wrote:
> 
> >On Sun, 31 Jul 2011 11:09:56 -0700 H. Peter Anvin wrote:
> >
> >> On 07/31/2011 11:07 AM, Mike Waychison wrote:
> >> >>>
> >> >>> Internal-reference-ID: rdunlap.2011.0729.id1
> >> >>>
> >> > 
> >> > Acked-by: Mike Waychison <mikew@google.com>
> >> > 
> >> 
> >> Just to avoid namespace collisions, can we at least put the owner
> >> somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google>
> >and
> >> so on?
> >
> >I would prefer to leave the text contents as unspecified, but I
> >wouldn't
> >mind recommending that users try to make them unique, e.g., by using
> >a company-ID or owner-ID.  Would that be acceptable?
> >
> >
> >---
> >~Randy
> >*** Remember to use Documentation/SubmitChecklist when testing your
> >code ***
> 
> No, that wouldn't work when there is more than one tag from different users.  And yes, I fully expect to see that.
> -- 

I guess that's a NAK or at least not consensus.
Would you like to submit an alternative?

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

On 08/14/2011 08:23 PM, Randy Dunlap wrote:
>>
>> No, that wouldn't work when there is more than one tag from different users.  And yes, I fully expect to see that.
>> --
>
> I guess that's a NAK or at least not consensus.
> Would you like to submit an alternative?
>

I would like to see the <id@owner> format I mentioned.

	-hpa

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Mike Waychison]

On Sun, Aug 14, 2011 at 10:19 PM, H. Peter Anvin <hpa@zytor.com> wrote:
> On 08/14/2011 08:23 PM, Randy Dunlap wrote:
>>>
>>> No, that wouldn't work when there is more than one tag from different
>>> users.  And yes, I fully expect to see that.
>>> --
>>
>> I guess that's a NAK or at least not consensus.
>> Would you like to submit an alternative?
>>
>
> I would like to see the <id@owner> format I mentioned.

Is there a middle ground if we say:

Internal-reference-ID: <arbitrarytextforid@owner>

so

Internal-reference-ID: <2011.0729.id1@rdunlap>
Internal-reference-ID: <bug-45322143@google>

?

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

On 08/15/2011 10:39 AM, Mike Waychison wrote:
>>
>> I would like to see the <id@owner> format I mentioned.
> 
> Is there a middle ground if we say:
> 
> Internal-reference-ID: <arbitrarytextforid@owner>
> 
> so
> 
> Internal-reference-ID: <2011.0729.id1@rdunlap>
> Internal-reference-ID: <bug-45322143@google>
> 

Personally I don't care if they are separate lines or all on the same line.

	-hpa

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Arnaud Lacombe]

Hi,

On Fri, Jul 29, 2011 at 9:00 PM, Randy Dunlap <rdunlap@xenotime.net> wrote:
> From: Randy Dunlap <rdunlap@xenotime.net>
>
> Introduce "Internal-reference-ID:" for company-internal
> patch tracking.  Also clarify that URLs in patches should be
> public, not private.
>
> Based on emails from Greg Kroah-Hartman.
>
> Internal-reference-ID: rdunlap.2011.0729.id1
>
What's the point of this for individuals ? Couldn't the Message-id
from the mail be re-used ?

 - Arnaud

> Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> Cc: Mike Waychison <mikew@google.com>
> Cc: Greg Kroah-Hartman <gregkh@suse.de>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: "H. Peter Anvin" <hpa@zytor.com>
> Cc: Theodore Tso <tytso@MIT.EDU>
> Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
> ---
>  Documentation/SubmittingPatches |   25 ++++++++++++++++++++++---
>  1 file changed, 22 insertions(+), 3 deletions(-)
>
> --- linux-3.0-git11.orig/Documentation/SubmittingPatches
> +++ linux-3.0-git11/Documentation/SubmittingPatches
> @@ -108,7 +108,14 @@ This benefits both the patch merger(s) a
>  probably didn't even receive earlier versions of the patch.
>
>  If the patch fixes a logged bug entry, refer to that bug entry by
> -number and URL.
> +number and URL (for URLs that are public, i.e., available to
> +everyone).
> +
> +Please don't include private (internal) URLs in patch descriptions,
> +so just say something like:
> +       Fixes fubar.com bugzilla #4311
> +instead of
> +       Fixes bugzilla.fubar.com/show_bug.cgi?id=4311
>
>
>  3) Separate your changes.
> @@ -469,7 +476,19 @@ understand the subject area and to perfo
>  increase the likelihood of your patch getting into the kernel.
>
>
> -15) The canonical patch format
> +15) Internal-reference-ID: tag
> +
> +Sometimes a company wants to include an internal reference ID (tag)
> +in a patch so that they can have better patch tracking.  Instead of
> +having a bazillion different such ID tags, the accepted one for
> +everyone to use is:
> +
> +Internal-reference-ID: <text>
> +
> +<text> should not be a private (internal) URL.
> +
> +
> +16) The canonical patch format
>
>  The canonical patch subject line is:
>
> @@ -583,7 +602,7 @@ See more details on the proper patch for
>  references.
>
>
> -16) Sending "git pull" requests  (from Linus emails)
> +17) Sending "git pull" requests  (from Linus emails)
>
>  Please write the git repo address and branch name alone on the same line
>  so that I can't even by mistake pull from the wrong branch, and so
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
>

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

On Mon, 15 Aug 2011 14:36:41 -0400 Arnaud Lacombe wrote:

> Hi,
> 
> On Fri, Jul 29, 2011 at 9:00 PM, Randy Dunlap <rdunlap@xenotime.net> wrote:
> > From: Randy Dunlap <rdunlap@xenotime.net>
> >
> > Introduce "Internal-reference-ID:" for company-internal
> > patch tracking.  Also clarify that URLs in patches should be
> > public, not private.
> >
> > Based on emails from Greg Kroah-Hartman.
> >
> > Internal-reference-ID: rdunlap.2011.0729.id1
> >
> What's the point of this for individuals ? Couldn't the Message-id
> from the mail be re-used ?
> 
>  - Arnaud

Individuals or companies might like to track their upstream patches
easily.  A pseudo-random message-id doesn't do that (for me).


> > Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
> > Cc: Mike Waychison <mikew@google.com>
> > Cc: Greg Kroah-Hartman <gregkh@suse.de>
> > Cc: Andrew Morton <akpm@linux-foundation.org>
> > Cc: "H. Peter Anvin" <hpa@zytor.com>
> > Cc: Theodore Tso <tytso@MIT.EDU>
> > Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>
> > ---
> >  Documentation/SubmittingPatches |   25 ++++++++++++++++++++++---
> >  1 file changed, 22 insertions(+), 3 deletions(-)
> >
> > --- linux-3.0-git11.orig/Documentation/SubmittingPatches
> > +++ linux-3.0-git11/Documentation/SubmittingPatches
> > @@ -108,7 +108,14 @@ This benefits both the patch merger(s) a
> >  probably didn't even receive earlier versions of the patch.
> >
> >  If the patch fixes a logged bug entry, refer to that bug entry by
> > -number and URL.
> > +number and URL (for URLs that are public, i.e., available to
> > +everyone).
> > +
> > +Please don't include private (internal) URLs in patch descriptions,
> > +so just say something like:
> > +       Fixes fubar.com bugzilla #4311
> > +instead of
> > +       Fixes bugzilla.fubar.com/show_bug.cgi?id=4311
> >
> >
> >  3) Separate your changes.
> > @@ -469,7 +476,19 @@ understand the subject area and to perfo
> >  increase the likelihood of your patch getting into the kernel.
> >
> >
> > -15) The canonical patch format
> > +15) Internal-reference-ID: tag
> > +
> > +Sometimes a company wants to include an internal reference ID (tag)
> > +in a patch so that they can have better patch tracking.  Instead of
> > +having a bazillion different such ID tags, the accepted one for
> > +everyone to use is:
> > +
> > +Internal-reference-ID: <text>
> > +
> > +<text> should not be a private (internal) URL.
> > +
> > +
> > +16) The canonical patch format
> >
> >  The canonical patch subject line is:
> >
> > @@ -583,7 +602,7 @@ See more details on the proper patch for
> >  references.
> >
> >
> > -16) Sending "git pull" requests  (from Linus emails)
> > +17) Sending "git pull" requests  (from Linus emails)
> >
> >  Please write the git repo address and branch name alone on the same line
> >  so that I can't even by mistake pull from the wrong branch, and so
> > --


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

On Mon, 15 Aug 2011 11:27:53 -0700 H. Peter Anvin wrote:

> On 08/15/2011 10:39 AM, Mike Waychison wrote:
> >>
> >> I would like to see the <id@owner> format I mentioned.
> > 
> > Is there a middle ground if we say:
> > 
> > Internal-reference-ID: <arbitrarytextforid@owner>
> > 
> > so
> > 
> > Internal-reference-ID: <2011.0729.id1@rdunlap>
> > Internal-reference-ID: <bug-45322143@google>
> > 
> 
> Personally I don't care if they are separate lines or all on the same line.

I don't understand how that answers Mike's question...

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

On 08/15/2011 01:23 PM, Randy Dunlap wrote:
> On Mon, 15 Aug 2011 11:27:53 -0700 H. Peter Anvin wrote:
> 
>> On 08/15/2011 10:39 AM, Mike Waychison wrote:
>>>>
>>>> I would like to see the <id@owner> format I mentioned.
>>>
>>> Is there a middle ground if we say:
>>>
>>> Internal-reference-ID: <arbitrarytextforid@owner>
>>>
>>> so
>>>
>>> Internal-reference-ID: <2011.0729.id1@rdunlap>
>>> Internal-reference-ID: <bug-45322143@google>
>>>
>>
>> Personally I don't care if they are separate lines or all on the same line.
> 
> I don't understand how that answers Mike's question...
> 
Then I don't understand the question.

I proposed:

Internal-reference-ID: <2011.0729.id1@rdunlap> <33999@google>

Mike proposed:

Internal-reference-ID: <2011.0729.id1@rdunlap>
Internal-reference-ID: <bug-45322143@google>

The only difference I see is if they are on the same line, which I don't
personally care about.

	-hpa

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Randy Dunlap]

On Mon, 15 Aug 2011 13:47:23 -0700 H. Peter Anvin wrote:

> On 08/15/2011 01:23 PM, Randy Dunlap wrote:
> > On Mon, 15 Aug 2011 11:27:53 -0700 H. Peter Anvin wrote:
> > 
> >> On 08/15/2011 10:39 AM, Mike Waychison wrote:
> >>>>
> >>>> I would like to see the <id@owner> format I mentioned.
> >>>
> >>> Is there a middle ground if we say:
> >>>
> >>> Internal-reference-ID: <arbitrarytextforid@owner>
> >>>
> >>> so
> >>>
> >>> Internal-reference-ID: <2011.0729.id1@rdunlap>
> >>> Internal-reference-ID: <bug-45322143@google>
> >>>
> >>
> >> Personally I don't care if they are separate lines or all on the same line.
> > 
> > I don't understand how that answers Mike's question...
> > 
> Then I don't understand the question.

OK, I see.

> I proposed:
> 
> Internal-reference-ID: <2011.0729.id1@rdunlap> <33999@google>

You said (on July-31):
"Just to avoid namespace collisions, can we at least put the owner
somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google> and
so on?"

I read that as 2 different patches & 2 different IDs, but this more
recent line:
> Internal-reference-ID: <2011.0729.id1@rdunlap> <33999@google>

would be for one patch with multiple IDs.


> Mike proposed:
> 
> Internal-reference-ID: <2011.0729.id1@rdunlap>
> Internal-reference-ID: <bug-45322143@google>

I think that Mike was just giving 2 examples (for 2 patches).  His proposal
was simply for:
Internal-reference-ID: <arbitrarytextforid@owner>

which matches your request fairly well AFAICT.

But if we are changing things, I think I prefer your other suggestion
for the ID tag:  "Patch-ID".  I like it because it's shorter and
easier to type.  :)


> The only difference I see is if they are on the same line, which I don't
> personally care about.


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[H. Peter Anvin]

On 08/15/2011 02:00 PM, Randy Dunlap wrote:
> 
> You said (on July-31):
> "Just to avoid namespace collisions, can we at least put the owner
> somewhere standardized, e.g. <2011.0729.id1@rdunlap>, <33999@google> and
> so on?"
> 
> I read that as 2 different patches & 2 different IDs, but this more
> recent line:
>> Internal-reference-ID: <2011.0729.id1@rdunlap> <33999@google>
> 
> would be for one patch with multiple IDs.
> 
>> Mike proposed:
>>
>> Internal-reference-ID: <2011.0729.id1@rdunlap>
>> Internal-reference-ID: <bug-45322143@google>
> 
> I think that Mike was just giving 2 examples (for 2 patches).  His proposal
> was simply for:
> Internal-reference-ID: <arbitrarytextforid@owner>
> 
> which matches your request fairly well AFAICT.
> 

Yes, that was my request.  But I also do observe that a single patch can
be tracked in multiple internal databases; for example, if
(hypothetically) Red Hat reports a bug to Google which ends up being
tracked in both bug databases, they may both want to tag the same patch.

> But if we are changing things, I think I prefer your other suggestion
> for the ID tag:  "Patch-ID".  I like it because it's shorter and
> easier to type.  :)

Agreed.

	-hpa

Re: [PATCH] Documentation: add Internal-reference-ID: patch tag

[Florian Mickler]

On Mon, 15 Aug 2011 13:12:13 -0700
Randy Dunlap <rdunlap@xenotime.net> wrote:

> On Mon, 15 Aug 2011 14:36:41 -0400 Arnaud Lacombe wrote:
> 
> > Hi,
> > 
> > On Fri, Jul 29, 2011 at 9:00 PM, Randy Dunlap <rdunlap@xenotime.net> wrote:
> > > From: Randy Dunlap <rdunlap@xenotime.net>
> > >
> > > Introduce "Internal-reference-ID:" for company-internal
> > > patch tracking.  Also clarify that URLs in patches should be
> > > public, not private.
> > >
> > > Based on emails from Greg Kroah-Hartman.
> > >
> > > Internal-reference-ID: rdunlap.2011.0729.id1
> > >
> > What's the point of this for individuals ? Couldn't the Message-id
> > from the mail be re-used ?
> > 
> >  - Arnaud
> 
> Individuals or companies might like to track their upstream patches
> easily.  A pseudo-random message-id doesn't do that (for me).

Also when parsing the changelog it is nice to be able to skip those
lines by common prefix. Without prefix you can easily get
trapped by the <id-text> having similar patterns to what you look
for. 

Regards,
Flo