Skip to contentSkip to conversation

doc: add suggestions about good practises for maintainers

PATCH In review Willy Tarreau 2 participants 3 messages Jun 3, 2008 – Jun 4, 2008 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: add suggestions about good practises for maintainers

Linus,

I'm proposing the following add-on to SubmittingPatches. I think it clarifies the situation for maintainers and back-porters.

Regards,
Willy
--

Quoted 1 line

From 1bf91b1072323ae3150c8962f36092b5b8528c48 Mon Sep 17 00:00:00 2001

From: Willy Tarreau <[email protected]>
Date: Tue, 3 Jun 2008 00:20:28 +0200
Subject: doc: add suggestions about good practises for maintainers

Suggest how to deal with patch modifications caused by merging or back-porting when you're a maintainer.

---
 Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)
Documentation/SubmittingPatches +46 -0
index 9c93a03..6e7183b 100644
@@ -327,6 +327,52 @@ Some people also put extra tags at the end.  They'll just be ignored for
 now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off. 
 
+If you are a subsystem or branch maintainer, sometimes you need to slightly
+modify patches you receive in order to merge them, because the code is not
+exactly the same in your tree and the submitters'. If you stick strictly to
+rule (c), you should ask the submitter to rediff, but this is a totally
+counter-productive waste of time and energy. Rule (b) allows you to adjust
+the code, but then it is very impolite to change one submitter's code and
+make him endorse your bugs. To solve this problem, it is recommended that
+you add a line between the last Signed-off-by header and yours, indicating
+the nature of your changes. While there is nothing mandatory about this, it
+seems like prepending the description with your mail and/or name, all
+enclosed in square brackets, is noticeable enough to make it obvious that
+you are responsible for last-minute changes. Example :
+
+	Signed-off-by: Random J Developer <[email protected]>
+	[[email protected]: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <[email protected]>
+
+This practise is particularly helpful if you maintain a stable branch and
+want at the same time to credit the author, track changes, merge the fix,
+and protect the submitter from complaints. Note that under no ciscumstances
+you can change the author's identity (the From header), as it is the one
+which appears in the changelog.
+
+Special note to back-porters. It seems to be a common and useful practise
+to insert an indication of the origin of a patch at the top of the commit
+message (just after the subject line) to facilitate tracking. For instance,
+here's what we see in 2.6-stable :
+
+    Date:   Tue May 13 19:10:30 2008 +0000
+
+        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+And here's what appears in 2.4 :
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+Whatever the format, this information provides a valuable help to people
+tracking your trees, and to people trying to trouble-shoot bugs in your
+tree.
+
 
 13) When to use Acked-by: and Cc:
 
Signature · 4 lines
1.5.3.8


----- End forwarded message -----
#1 lore raw
Quoted 40 lines · On Tue, 3 Jun 2008 07:34:46 +0200 Willy Tarreau wrote:

Linus,

I'm proposing the following add-on to SubmittingPatches. I think it clarifies the situation for maintainers and back-porters.

Regards,
Willy
--

Quoted 1 line

From 1bf91b1072323ae3150c8962f36092b5b8528c48 Mon Sep 17 00:00:00 2001

From: Willy Tarreau <[email protected]>
Date: Tue, 3 Jun 2008 00:20:28 +0200
Subject: doc: add suggestions about good practises for maintainers

Suggest how to deal with patch modifications caused by merging or back-porting when you're a maintainer.

---
 Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)
Documentation/SubmittingPatches +10 -0
index 9c93a03..6e7183b 100644
@@ -327,6 +327,52 @@ Some people also put extra tags at the end.  They'll just be ignored for
 now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off. 
 
+If you are a subsystem or branch maintainer, sometimes you need to slightly
+modify patches you receive in order to merge them, because the code is not
+exactly the same in your tree and the submitters'. If you stick strictly to
+rule (c), you should ask the submitter to rediff, but this is a totally
+counter-productive waste of time and energy. Rule (b) allows you to adjust
+the code, but then it is very impolite to change one submitter's code and
+make him endorse your bugs. To solve this problem, it is recommended that
+you add a line between the last Signed-off-by header and yours, indicating
+the nature of your changes. While there is nothing mandatory about this, it
+seems like prepending the description with your mail and/or name, all

Documentation/SubmittingPatches Some people also put extra tags at the end. They'll just be ignored for · line 349

Quoted 10 lines
Documentation/SubmittingPatches +10 -0
+enclosed in square brackets, is noticeable enough to make it obvious that
+you are responsible for last-minute changes. Example :
+
+	Signed-off-by: Random J Developer <[email protected]>
+	[[email protected]: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <[email protected]>
+
+This practise is particularly helpful if you maintain a stable branch and
+want at the same time to credit the author, track changes, merge the fix,
+and protect the submitter from complaints. Note that under no ciscumstances

circumstances

Documentation/SubmittingPatches Some people also put extra tags at the end. They'll just be ignored for · line 350

Quoted 1 line
Documentation/SubmittingPatches +1 -0
+you can change the author's identity (the From header), as it is the one

can you change

Documentation/SubmittingPatches Some people also put extra tags at the end. They'll just be ignored for · line 353

Quoted 3 lines
Documentation/SubmittingPatches +3 -0
+which appears in the changelog.
+
+Special note to back-porters. It seems to be a common and useful practise

back-porters:

Quoted 16 lines
Documentation/SubmittingPatches +15 -0
+to insert an indication of the origin of a patch at the top of the commit
+message (just after the subject line) to facilitate tracking. For instance,
+here's what we see in 2.6-stable :
+
+    Date:   Tue May 13 19:10:30 2008 +0000
+
+        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+And here's what appears in 2.4 :
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay

Documentation/SubmittingPatches Some people also put extra tags at the end. They'll just be ignored for · line 378

Quoted 10 lines
Documentation/SubmittingPatches +7 -0
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+Whatever the format, this information provides a valuable help to people
+tracking your trees, and to people trying to trouble-shoot bugs in your
+tree.
+
 
 13) When to use Acked-by: and Cc:
 

---
~Randy

#2 lore raw

Thank you for your comments Randy.

Linus, please use the following one instead.

Thanks!
Willy
--

Quoted 1 line

From 2612e19e0827be56bd185a4cdd69bafaa05f8b46 Mon Sep 17 00:00:00 2001

From: Willy Tarreau <[email protected]>
Date: Tue, 3 Jun 2008 00:20:28 +0200
Subject: doc: add suggestions about good practises for maintainers

Suggest how to deal with patch modifications caused by merging or back-porting when you're a maintainer.

---
 Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)
Documentation/SubmittingPatches +46 -0
index 9c93a03..118ca6e 100644
@@ -327,6 +327,52 @@ Some people also put extra tags at the end.  They'll just be ignored for
 now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off. 
 
+If you are a subsystem or branch maintainer, sometimes you need to slightly
+modify patches you receive in order to merge them, because the code is not
+exactly the same in your tree and the submitters'. If you stick strictly to
+rule (c), you should ask the submitter to rediff, but this is a totally
+counter-productive waste of time and energy. Rule (b) allows you to adjust
+the code, but then it is very impolite to change one submitter's code and
+make him endorse your bugs. To solve this problem, it is recommended that
+you add a line between the last Signed-off-by header and yours, indicating
+the nature of your changes. While there is nothing mandatory about this, it
+seems like prepending the description with your mail and/or name, all
+enclosed in square brackets, is noticeable enough to make it obvious that
+you are responsible for last-minute changes. Example :
+
+	Signed-off-by: Random J Developer <[email protected]>
+	[[email protected]: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <[email protected]>
+
+This practise is particularly helpful if you maintain a stable branch and
+want at the same time to credit the author, track changes, merge the fix,
+and protect the submitter from complaints. Note that under no circumstances
+can you change the author's identity (the From header), as it is the one
+which appears in the changelog.
+
+Special note to back-porters: It seems to be a common and useful practise
+to insert an indication of the origin of a patch at the top of the commit
+message (just after the subject line) to facilitate tracking. For instance,
+here's what we see in 2.6-stable :
+
+    Date:   Tue May 13 19:10:30 2008 +0000
+
+        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+And here's what appears in 2.4 :
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+Whatever the format, this information provides a valuable help to people
+tracking your trees, and to people trying to trouble-shoot bugs in your
+tree.
+
 
 13) When to use Acked-by: and Cc:
 
Signature · 1 line
1.5.3.8