| Message ID | 20200417222430.20480-1-sstabellini@kernel.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] Introduce a description of the Backport and Fixes tags | expand |
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>
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,
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.
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
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
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
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.
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.
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
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.
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