[PATCH] SubmittingPatches: add more about patch descriptions

From: Randy Dunlap
Date: Tue Jun 15 2010 - 12:18:45 EST

On Tue, 15 Jun 2010 08:53:02 -0400 tytso@xxxxxxx wrote:

> On Tue, Jun 15, 2010 at 12:43:17AM +0200, Tejun Heo wrote:
> >
> > Well, basics of the whole thing didn't change all that much since the
> > first take and most people on cc list were cc'd on each take. The
> > biggest reason I'm still carrying the whole patchset is due to the
> > scheduler changes. The numbers are in the third take (which you can
> > follow the links to find out). Anyways, I'll write up another summary
> > tomorrow.
> It really helps if patch summaries are self contained and don't
> require a bunch of kernel developers who are trying to review things
> to have to do research and then figure out which links are the right
> ones to chase down. It's also not reasonable to expect your reviewers
> to diff your patches to determine how much has changed and whether
> they should expect benchmarks run from months ago to still be
> applicable or not.
> Many of us get literally hundreds of e-mail messages a day, and
> e-mails are read with one finger hovering over the the 'd' key. It
> simply scales better if you don't assume that everybody else considers
> the patch as important as you do, and instead assume that most people
> have forgotten patches sent months ago....

Ack that.

Does this help? anything need to be added to it?

From: Randy Dunlap <randy.dunlap@xxxxxxxxxx>

Add more information about patch descriptions.

Signed-off-by: Randy Dunlap <randy.dunlap@xxxxxxxxxx>
Documentation/SubmittingPatches | 11 +++++++++++
1 file changed, 11 insertions(+)

--- lnx-2635-rc3.orig/Documentation/SubmittingPatches
+++ lnx-2635-rc3/Documentation/SubmittingPatches
@@ -98,6 +98,17 @@ system, git, as a "commit log". See #15
If your description starts to get long, that's a sign that you probably
need to split up your patch. See #3, next.

+When you submit or resubmit a patch or patch series, include the
+complete patch description and justification for it. Don't just
+say that this is version N of the patch (series). Don't expect the
+patch merger to refer back to earlier patch versions or referenced
+URLs to find the patch description and put that into the patch.
+I.e., the patch (series) and its description should be self-contained.
+This benefits both the patch merger(s) and reviewers. Some reviewers
+probably didn't even receive earlier versions of the patch.
+If the patch fixes a logged bug entry, refer to that bug entry by
+number and URL.

3) Separate your changes.
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/