Introduce a description of the Backport and Fixes tags
PATCH v3 1/1 Introduce a description of the Backport and Fixes tags
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.
---
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
docs/process/tags.pandoc new file +55 -0
@@ -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.
Signature · 1 line
2.17.1
Quoted 4 lines · 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.
Quoted 9 lines
Signed-off-by Stefano Stabellini <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>
Hi Stefano,
Quoted 26 lines · 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 <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>---
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
docs/process/tags.pandoc new file +0
-0
docs/process/tags.pandoc line 7
Quoted 7 lines
docs/process/tags.pandoc new file +7
-0@@ -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...
docs/process/tags.pandoc line 15
Quoted 8 lines
docs/process/tags.pandoc new file +8
-0+ + +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.
Quoted 31 lines
docs/process/tags.pandoc new file +30
-0+ +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
docs/process/tags.pandoc line 55
Quoted 10 lines
docs/process/tags.pandoc new file +10
-0+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,
Signature · 1 line
Julien Grall
Quoted 50 lines · Julien Grall
Hi Stefano,
Quoted 26 lines · 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 <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>---
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
docs/process/tags.pandoc new file +0
-0docs/process/tags.pandoc line 7
Quoted 7 lines
docs/process/tags.pandoc new file +7
-0@@ -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...
docs/process/tags.pandoc line 15
Quoted 8 lines
docs/process/tags.pandoc new file +8
-0+ + +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?
Quoted 3 lines
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.
Quoted 49 lines · Wei Liu
Quoted 48 lines · Julien Grall
Quoted 26 lines · 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 <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>---
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
docs/process/tags.pandoc new file +0
-0docs/process/tags.pandoc line 7
Quoted 7 lines
docs/process/tags.pandoc new file +7
-0@@ -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...
docs/process/tags.pandoc line 15
Quoted 8 lines
docs/process/tags.pandoc new file +8
-0+ + +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?
Quoted 7 lines
Quoted 3 lines
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
Quoted 54 lines · Jan Beulich
Quoted 53 lines · Wei Liu
Quoted 51 lines · Julien Grall
Quoted 26 lines · 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 <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>---
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
docs/process/tags.pandoc new file +0
-0docs/process/tags.pandoc line 7
Quoted 7 lines
docs/process/tags.pandoc new file +7
-0@@ -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...
docs/process/tags.pandoc line 15
Quoted 8 lines
docs/process/tags.pandoc new file +8
-0+ + +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.
Quoted 6 lines
Quoted 3 lines
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.
Quoted 2 lines
Jan
docs/process/tags.pandoc line 35
Quoted 10 lines · Stefano Stabellini
docs/process/tags.pandoc new file +10
-0+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"?
Quoted 9 lines
docs/process/tags.pandoc new file +9
-0+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
docs/process/tags.pandoc line 55
Quoted 10 lines
docs/process/tags.pandoc new file +10
-0+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
Quoted 54 lines · Jan Beulich
Quoted 53 lines · Wei Liu
Quoted 51 lines · Julien Grall
Quoted 26 lines · 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 <[email protected]>CC Ian Jackson <[email protected]>CC Wei Liu <[email protected]>---
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
docs/process/tags.pandoc new file +0
-0docs/process/tags.pandoc line 7
Quoted 7 lines
docs/process/tags.pandoc new file +7
-0@@ -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...
docs/process/tags.pandoc line 15
Quoted 8 lines
docs/process/tags.pandoc new file +8
-0+ + +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.
Quoted 6 lines
Quoted 3 lines
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.
Quoted 15 lines · Jan Beulich
docs/process/tags.pandoc line 35
Quoted 10 lines · Stefano Stabellini
docs/process/tags.pandoc new file +10
-0+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
Quoted 15 lines
Quoted 15 lines
docs/process/tags.pandoc new file +15
-0+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.
Quoted 8 lines
docs/process/tags.pandoc line 55
Quoted 4 lines
docs/process/tags.pandoc new file +4
-0+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
Quoted 5 lines
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:
Quoted 2 lines
Quoted 2 lines
docs/process/tags.pandoc new file +2
-0+Maintainers might ask the requester to help with the backporting work if +it is not trivial.
Quoted 9 lines · Stefano Stabellini
Quoted 6 lines · Jan Beulich
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.)
Quoted 4 lines
I didn't reply, but I added two lines in that regards, see also above:
Quoted 2 lines
docs/process/tags.pandoc line 53
Quoted 2 lines
docs/process/tags.pandoc new file +2
-0+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