[PATCH v3] Introduce a description of the Backport and Fixes tags

[PATCH v3] Introduce a description of the Backport and Fixes tags

[Stefano Stabellini]

Create a new document under docs/process to describe our special tags.
Add a description of the Fixes tag and the new Backport tag. Also
clarify that lines with tags should not be split.

Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
CC: Ian Jackson <ian.jackson@eu.citrix.com>
CC: Wei Liu <wl@xen.org>
CC: jbeulich@suse.com
CC: george.dunlap@citrix.com
CC: julien@xen.org
CC: lars.kurth@citrix.com
CC: andrew.cooper3@citrix.com
CC: konrad.wilk@oracle.com
---
Removing Acks as I added the description of "Fixes"
---
 docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/process/tags.pandoc

diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
new file mode 100644
index 0000000000..06b06dda01
--- /dev/null
+++ b/docs/process/tags.pandoc
@@ -0,0 +1,55 @@
+Tags: No line splitting
+-----------------------
+Do not split a tag across multiple lines, tags are exempt from the
+"wrap at 75 columns" rule in order to simplify parsing scripts.  For
+example:
+
+        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
+
+
+Fixes Tag
+---------
+
+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.
+
+The following ``git config`` settings can be used to add a pretty format for
+outputting the above style in the ``git log`` or ``git show`` commands:
+
+        [core]
+                abbrev = 12
+        [pretty]
+                fixes = Fixes: %h (\"%s\")
+
+
+Backport Tag
+------------
+
+A backport tag is an optional tag in the commit message to request a
+given commit to be backported to the stable trees:
+
+    Backport: 4.9+
+
+It marks a commit for being a candidate for backports to all stable
+trees from 4.9 onward.
+
+The backport requester is expected to specify which currently supported
+releases need the backport; but encouraged to specify a release as far
+back as possible which applies. If the requester doesn't know the oldest
+affected tree, they are encouraged to append a comment like the
+following:
+
+    Backport: 4.9+ # maybe older
+
+Maintainers request the Backport tag to be added on commit. Contributors
+are welcome to mark their patches with the Backport tag when they deem
+appropriate. Maintainers will request for it to be removed when that is
+not the case.
+
+Please note that the Backport tag is a **request** for backport, which
+will still need to be evaluated by the stable tree maintainers.
+Maintainers might ask the requester to help with the backporting work if
+it is not trivial.
+
+When possible, please use the Fixes tag instead.
-- 
2.17.1

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Wei Liu]

On Fri, Apr 17, 2020 at 03:24:30PM -0700, Stefano Stabellini wrote:
> Create a new document under docs/process to describe our special tags.
> Add a description of the Fixes tag and the new Backport tag. Also
> clarify that lines with tags should not be split.
> 
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
> CC: Ian Jackson <ian.jackson@eu.citrix.com>
> CC: Wei Liu <wl@xen.org>
> CC: jbeulich@suse.com
> CC: george.dunlap@citrix.com
> CC: julien@xen.org
> CC: lars.kurth@citrix.com
> CC: andrew.cooper3@citrix.com
> CC: konrad.wilk@oracle.com

Acked-by: Wei Liu <wl@xen.org>

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Julien Grall]

Hi Stefano,

On 17/04/2020 23:24, Stefano Stabellini wrote:
> Create a new document under docs/process to describe our special tags.
> Add a description of the Fixes tag and the new Backport tag. Also
> clarify that lines with tags should not be split.
> 
> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
> CC: Ian Jackson <ian.jackson@eu.citrix.com>
> CC: Wei Liu <wl@xen.org>
> CC: jbeulich@suse.com
> CC: george.dunlap@citrix.com
> CC: julien@xen.org
> CC: lars.kurth@citrix.com
> CC: andrew.cooper3@citrix.com
> CC: konrad.wilk@oracle.com
> ---
> Removing Acks as I added the description of "Fixes"
> ---
>   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 55 insertions(+)
>   create mode 100644 docs/process/tags.pandoc
> 
> diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
> new file mode 100644
> index 0000000000..06b06dda01
> --- /dev/null
> +++ b/docs/process/tags.pandoc
> @@ -0,0 +1,55 @@
> +Tags: No line splitting
> +-----------------------
> +Do not split a tag across multiple lines, tags are exempt from the
> +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
> +example:
> +
> +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")

The SHA-1 ID is 9 characters but...

> +
> +
> +Fixes Tag
> +---------
> +
> +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.

... you request 12 characters here. Can you make sure the two match please?

However, I am not entirely sure why we should mandate 12 characters. 
With the title, you should always be able to find back the commit if 
there is a clash.

> +
> +The following ``git config`` settings can be used to add a pretty format for
> +outputting the above style in the ``git log`` or ``git show`` commands:
> +
> +        [core]
> +                abbrev = 12
> +        [pretty]
> +                fixes = Fixes: %h (\"%s\")
> +
> +
> +Backport Tag
> +------------
> +
> +A backport tag is an optional tag in the commit message to request a
> +given commit to be backported to the stable trees:
> +
> +    Backport: 4.9+
> +
> +It marks a commit for being a candidate for backports to all stable
> +trees from 4.9 onward.
> +
> +The backport requester is expected to specify which currently supported
> +releases need the backport; but encouraged to specify a release as far
> +back as possible which applies. If the requester doesn't know the oldest
> +affected tree, they are encouraged to append a comment like the
> +following:
> +
> +    Backport: 4.9+ # maybe older
> +
> +Maintainers request the Backport tag to be added on commit. Contributors
> +are welcome to mark their patches with the Backport tag when they deem
> +appropriate. Maintainers will request for it to be removed when that is
> +not the case.
> +
> +Please note that the Backport tag is a **request** for backport, which
> +will still need to be evaluated by the stable tree maintainers.
> +Maintainers might ask the requester to help with the backporting work if
> +it is not trivial.
> +
> +When possible, please use the Fixes tag instead.
> 

Cheers,

-- 
Julien Grall

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Wei Liu]

On Mon, Apr 20, 2020 at 10:31:28AM +0100, Julien Grall wrote:
> Hi Stefano,
> 
> On 17/04/2020 23:24, Stefano Stabellini wrote:
> > Create a new document under docs/process to describe our special tags.
> > Add a description of the Fixes tag and the new Backport tag. Also
> > clarify that lines with tags should not be split.
> > 
> > Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
> > CC: Ian Jackson <ian.jackson@eu.citrix.com>
> > CC: Wei Liu <wl@xen.org>
> > CC: jbeulich@suse.com
> > CC: george.dunlap@citrix.com
> > CC: julien@xen.org
> > CC: lars.kurth@citrix.com
> > CC: andrew.cooper3@citrix.com
> > CC: konrad.wilk@oracle.com
> > ---
> > Removing Acks as I added the description of "Fixes"
> > ---
> >   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 55 insertions(+)
> >   create mode 100644 docs/process/tags.pandoc
> > 
> > diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
> > new file mode 100644
> > index 0000000000..06b06dda01
> > --- /dev/null
> > +++ b/docs/process/tags.pandoc
> > @@ -0,0 +1,55 @@
> > +Tags: No line splitting
> > +-----------------------
> > +Do not split a tag across multiple lines, tags are exempt from the
> > +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
> > +example:
> > +
> > +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
> 
> The SHA-1 ID is 9 characters but...
> 
> > +
> > +
> > +Fixes Tag
> > +---------
> > +
> > +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.
> 
> ... you request 12 characters here. Can you make sure the two match please?
> 
> However, I am not entirely sure why we should mandate 12 characters. With
> the title, you should always be able to find back the commit if there is a
> clash.

This is copied from Linux's document.

I normally use 8-9 characters, but I don't mind using 12 either.

Wei.

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Jan Beulich]

On 20.04.2020 12:27, Wei Liu wrote:
> On Mon, Apr 20, 2020 at 10:31:28AM +0100, Julien Grall wrote:
>> On 17/04/2020 23:24, Stefano Stabellini wrote:
>>> Create a new document under docs/process to describe our special tags.
>>> Add a description of the Fixes tag and the new Backport tag. Also
>>> clarify that lines with tags should not be split.
>>>
>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
>>> CC: Ian Jackson <ian.jackson@eu.citrix.com>
>>> CC: Wei Liu <wl@xen.org>
>>> CC: jbeulich@suse.com
>>> CC: george.dunlap@citrix.com
>>> CC: julien@xen.org
>>> CC: lars.kurth@citrix.com
>>> CC: andrew.cooper3@citrix.com
>>> CC: konrad.wilk@oracle.com
>>> ---
>>> Removing Acks as I added the description of "Fixes"
>>> ---
>>>   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
>>>   1 file changed, 55 insertions(+)
>>>   create mode 100644 docs/process/tags.pandoc
>>>
>>> diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
>>> new file mode 100644
>>> index 0000000000..06b06dda01
>>> --- /dev/null
>>> +++ b/docs/process/tags.pandoc
>>> @@ -0,0 +1,55 @@
>>> +Tags: No line splitting
>>> +-----------------------
>>> +Do not split a tag across multiple lines, tags are exempt from the
>>> +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
>>> +example:
>>> +
>>> +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
>>
>> The SHA-1 ID is 9 characters but...
>>
>>> +
>>> +
>>> +Fixes Tag
>>> +---------
>>> +
>>> +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.
>>
>> ... you request 12 characters here. Can you make sure the two match please?
>>
>> However, I am not entirely sure why we should mandate 12 characters. With
>> the title, you should always be able to find back the commit if there is a
>> clash.
> 
> This is copied from Linux's document.
> 
> I normally use 8-9 characters, but I don't mind using 12 either.

Are they still saying 9? I've been asked to switch to 12 several
weeks back ...

Jan

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Wei Liu]

On Mon, Apr 20, 2020 at 02:36:49PM +0200, Jan Beulich wrote:
> On 20.04.2020 12:27, Wei Liu wrote:
> > On Mon, Apr 20, 2020 at 10:31:28AM +0100, Julien Grall wrote:
> >> On 17/04/2020 23:24, Stefano Stabellini wrote:
> >>> Create a new document under docs/process to describe our special tags.
> >>> Add a description of the Fixes tag and the new Backport tag. Also
> >>> clarify that lines with tags should not be split.
> >>>
> >>> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
> >>> CC: Ian Jackson <ian.jackson@eu.citrix.com>
> >>> CC: Wei Liu <wl@xen.org>
> >>> CC: jbeulich@suse.com
> >>> CC: george.dunlap@citrix.com
> >>> CC: julien@xen.org
> >>> CC: lars.kurth@citrix.com
> >>> CC: andrew.cooper3@citrix.com
> >>> CC: konrad.wilk@oracle.com
> >>> ---
> >>> Removing Acks as I added the description of "Fixes"
> >>> ---
> >>>   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
> >>>   1 file changed, 55 insertions(+)
> >>>   create mode 100644 docs/process/tags.pandoc
> >>>
> >>> diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
> >>> new file mode 100644
> >>> index 0000000000..06b06dda01
> >>> --- /dev/null
> >>> +++ b/docs/process/tags.pandoc
> >>> @@ -0,0 +1,55 @@
> >>> +Tags: No line splitting
> >>> +-----------------------
> >>> +Do not split a tag across multiple lines, tags are exempt from the
> >>> +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
> >>> +example:
> >>> +
> >>> +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
> >>
> >> The SHA-1 ID is 9 characters but...
> >>
> >>> +
> >>> +
> >>> +Fixes Tag
> >>> +---------
> >>> +
> >>> +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.
> >>
> >> ... you request 12 characters here. Can you make sure the two match please?
> >>
> >> However, I am not entirely sure why we should mandate 12 characters. With
> >> the title, you should always be able to find back the commit if there is a
> >> clash.
> > 
> > This is copied from Linux's document.
> > 
> > I normally use 8-9 characters, but I don't mind using 12 either.
> 
> Are they still saying 9? I've been asked to switch to 12 several
> weeks back ...

I mean when I work on Xen I normally use 8 or 9. Not sure about Linux.

Wei.

> 
> Jan

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Jan Beulich]

On 18.04.2020 00:24, Stefano Stabellini wrote:
> +Backport Tag
> +------------
> +
> +A backport tag is an optional tag in the commit message to request a
> +given commit to be backported to the stable trees:
> +
> +    Backport: 4.9+
> +
> +It marks a commit for being a candidate for backports to all stable
> +trees from 4.9 onward.

Using the wording "stable trees" may, to some, imply ones still
under maintenance. How about omitting "stable", or replacing it
by "released"?

> +The backport requester is expected to specify which currently supported
> +releases need the backport; but encouraged to specify a release as far
> +back as possible which applies. If the requester doesn't know the oldest
> +affected tree, they are encouraged to append a comment like the
> +following:
> +
> +    Backport: 4.9+ # maybe older
> +
> +Maintainers request the Backport tag to be added on commit. Contributors
> +are welcome to mark their patches with the Backport tag when they deem
> +appropriate. Maintainers will request for it to be removed when that is
> +not the case.
> +
> +Please note that the Backport tag is a **request** for backport, which
> +will still need to be evaluated by the stable tree maintainers.
> +Maintainers might ask the requester to help with the backporting work if
> +it is not trivial.
> +
> +When possible, please use the Fixes tag instead.

Maybe amend with "(or in addition)"? I'm thinking in particular
about a case where a buggy change was already backported, but
didn't show up yet in a release from the respective branch(es).

Previously I did suggest to add an indication that people requesting
backports should also be prepare to actually help with backporting.
I don't recall a verbal reply, and I also don't see any respective
update here. (I'm not fully trusting our mail system, i.e. it may
very well be that I did miss a reply.)

Jan

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Stefano Stabellini]

On Mon, 20 Apr 2020, Jan Beulich wrote:
> On 20.04.2020 12:27, Wei Liu wrote:
> > On Mon, Apr 20, 2020 at 10:31:28AM +0100, Julien Grall wrote:
> >> On 17/04/2020 23:24, Stefano Stabellini wrote:
> >>> Create a new document under docs/process to describe our special tags.
> >>> Add a description of the Fixes tag and the new Backport tag. Also
> >>> clarify that lines with tags should not be split.
> >>>
> >>> Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
> >>> CC: Ian Jackson <ian.jackson@eu.citrix.com>
> >>> CC: Wei Liu <wl@xen.org>
> >>> CC: jbeulich@suse.com
> >>> CC: george.dunlap@citrix.com
> >>> CC: julien@xen.org
> >>> CC: lars.kurth@citrix.com
> >>> CC: andrew.cooper3@citrix.com
> >>> CC: konrad.wilk@oracle.com
> >>> ---
> >>> Removing Acks as I added the description of "Fixes"
> >>> ---
> >>>   docs/process/tags.pandoc | 55 ++++++++++++++++++++++++++++++++++++++++
> >>>   1 file changed, 55 insertions(+)
> >>>   create mode 100644 docs/process/tags.pandoc
> >>>
> >>> diff --git a/docs/process/tags.pandoc b/docs/process/tags.pandoc
> >>> new file mode 100644
> >>> index 0000000000..06b06dda01
> >>> --- /dev/null
> >>> +++ b/docs/process/tags.pandoc
> >>> @@ -0,0 +1,55 @@
> >>> +Tags: No line splitting
> >>> +-----------------------
> >>> +Do not split a tag across multiple lines, tags are exempt from the
> >>> +"wrap at 75 columns" rule in order to simplify parsing scripts.  For
> >>> +example:
> >>> +
> >>> +        Fixes: 67d01cdb5 ("x86: infrastructure to allow converting certain indirect calls to direct ones")
> >>
> >> The SHA-1 ID is 9 characters but...
> >>
> >>> +
> >>> +
> >>> +Fixes Tag
> >>> +---------
> >>> +
> >>> +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.
> >>
> >> ... you request 12 characters here. Can you make sure the two match please?
> >>
> >> However, I am not entirely sure why we should mandate 12 characters. With
> >> the title, you should always be able to find back the commit if there is a
> >> clash.
> > 
> > This is copied from Linux's document.
> > 
> > I normally use 8-9 characters, but I don't mind using 12 either.
> 
> Are they still saying 9? I've been asked to switch to 12 several
> weeks back ...

Yes, I just took it from Linux. I don't care 9 or 12. Given the
preference for 12, I'll keep 12 in the text and update the example to
match.

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Stefano Stabellini]

On Mon, 20 Apr 2020, Jan Beulich wrote:
> On 18.04.2020 00:24, Stefano Stabellini wrote:
> > +Backport Tag
> > +------------
> > +
> > +A backport tag is an optional tag in the commit message to request a
> > +given commit to be backported to the stable trees:
> > +
> > +    Backport: 4.9+
> > +
> > +It marks a commit for being a candidate for backports to all stable
> > +trees from 4.9 onward.
> 
> Using the wording "stable trees" may, to some, imply ones still
> under maintenance. How about omitting "stable", or replacing it
> by "released"?

OK


> > +The backport requester is expected to specify which currently supported
> > +releases need the backport; but encouraged to specify a release as far
> > +back as possible which applies. If the requester doesn't know the oldest
> > +affected tree, they are encouraged to append a comment like the
> > +following:
> > +
> > +    Backport: 4.9+ # maybe older
> > +
> > +Maintainers request the Backport tag to be added on commit. Contributors
> > +are welcome to mark their patches with the Backport tag when they deem
> > +appropriate. Maintainers will request for it to be removed when that is
> > +not the case.
> > +
> > +Please note that the Backport tag is a **request** for backport, which
> > +will still need to be evaluated by the stable tree maintainers.
> > +Maintainers might ask the requester to help with the backporting work if
> > +it is not trivial.
> > +
> > +When possible, please use the Fixes tag instead.
> 
> Maybe amend with "(or in addition)"? I'm thinking in particular
> about a case where a buggy change was already backported, but
> didn't show up yet in a release from the respective branch(es).

Sure


> Previously I did suggest to add an indication that people requesting
> backports should also be prepare to actually help with backporting.
> I don't recall a verbal reply, and I also don't see any respective
> update here. (I'm not fully trusting our mail system, i.e. it may
> very well be that I did miss a reply.)


I didn't reply, but I added two lines in that regards, see also above:

> > +Maintainers might ask the requester to help with the backporting work if
> > +it is not trivial.

Re: [PATCH v3] Introduce a description of the Backport and Fixes tags

[Jan Beulich]

On 21.04.2020 20:22, Stefano Stabellini wrote:
> On Mon, 20 Apr 2020, Jan Beulich wrote:
>> On 18.04.2020 00:24, Stefano Stabellini wrote:
>> Previously I did suggest to add an indication that people requesting
>> backports should also be prepare to actually help with backporting.
>> I don't recall a verbal reply, and I also don't see any respective
>> update here. (I'm not fully trusting our mail system, i.e. it may
>> very well be that I did miss a reply.)
> 
> 
> I didn't reply, but I added two lines in that regards, see also above:
> 
>>> +Maintainers might ask the requester to help with the backporting work if
>>> +it is not trivial.

Oh, sorry, I simply didn't notice it in the place you put it.

Jan