[PATCH] doc: add suggestions about good practises for maintainers

[PATCH] doc: add suggestions about good practises for maintainers

[Willy Tarreau]

Linus,

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

Regards,
Willy
--

>From 1bf91b1072323ae3150c8962f36092b5b8528c48 Mon Sep 17 00:00:00 2001
From: Willy Tarreau <w@1wt.eu>
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.

Signed-off-by: Willy Tarreau <w@1wt.eu>
---
 Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c93a03..6e7183b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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 <random@developer.example.org>
+	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+
+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:
 
-- 
1.5.3.8


----- End forwarded message -----

Re: [PATCH] doc: add suggestions about good practises for maintainers

[Randy Dunlap]

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
> --
> 
> >From 1bf91b1072323ae3150c8962f36092b5b8528c48 Mon Sep 17 00:00:00 2001
> From: Willy Tarreau <w@1wt.eu>
> 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.
> 
> Signed-off-by: Willy Tarreau <w@1wt.eu>
> ---
>  Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
>  1 files changed, 46 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 9c93a03..6e7183b 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -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 <random@developer.example.org>
> +	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
> +	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
> +
> +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

> +you can change the author's identity (the From header), as it is the one

   can you change

> +which appears in the changelog.
> +
> +Special note to back-porters. It seems to be a common and useful practise

                   back-porters:

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

---
~Randy

Re: [PATCH] doc: add suggestions about good practises for maintainers

[Willy Tarreau]

Thank you for your comments Randy.

Linus, please use the following one instead.

Thanks!
Willy
--

>From 2612e19e0827be56bd185a4cdd69bafaa05f8b46 Mon Sep 17 00:00:00 2001
From: Willy Tarreau <w@1wt.eu>
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.

Signed-off-by: Willy Tarreau <w@1wt.eu>
---
 Documentation/SubmittingPatches |   46 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 46 insertions(+), 0 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c93a03..118ca6e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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 <random@developer.example.org>
+	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
+
+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:
 
-- 
1.5.3.8