Skip to contentSkip to conversation

Introduce a description of the Backport and Fixes tags

PATCH In review Stefano Stabellini 4 participants 10 messages Apr 17, 2020 – Apr 22, 2020

lore
Share & tools
lore
#0 lore raw

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
new file mode 100644
index 0000000000..06b06dda01
@@ -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
Acked-by on v3 1/1
#1 lore raw
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
#2 lore raw
In reply to Stefano Stabellini

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.

---
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
new file mode 100644
index 0000000000..06b06dda01

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
#3 lore raw
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.

---
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
new file mode 100644
index 0000000000..06b06dda01

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?

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.

#4 lore raw
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.

---
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
new file mode 100644
index 0000000000..06b06dda01

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?

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

#5 lore raw
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.

---
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
new file mode 100644
index 0000000000..06b06dda01

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 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

#7 lore raw
In reply to Stefano Stabellini

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

#6 lore raw
In reply to Jan Beulich
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.

---
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
new file mode 100644
index 0000000000..06b06dda01

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 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.

#8 lore raw
In reply to Jan Beulich
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.
#9 lore raw
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