doc: add suggestions about good practises for maintainers
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
1bf91b1072323ae3150c8962f36092b5b8528c48Mon 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
@@ -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 -----
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
1bf91b1072323ae3150c8962f36092b5b8528c48Mon Sep 17 00:00:00 2001From: Willy Tarreau <[email protected]>
Date: Tue, 3 Jun 2008 00:20:28 +0200
Subject: doc: add suggestions about good practises for maintainersSuggest how to deal with patch modifications caused by merging or back-porting when you're a maintainer.
Signed-off-by Willy Tarreau <[email protected]>--- Documentation/SubmittingPatches | 46 +++++++++++++++++++++++++++++++++++++++ 1 files changed, 46 insertions(+), 0 deletions(-)Documentation/SubmittingPatches +10
-0@@ -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
Thank you for your comments Randy.
Linus, please use the following one instead.
Thanks!
Willy
--
Quoted 1 line
From
2612e19e0827be56bd185a4cdd69bafaa05f8b46Mon 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
@@ -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