[PATCH] SubmittingPatches: add more about patch descriptions

[Randy Dunlap <randy.dunlap@oracle.com>]

On Tue, 15 Jun 2010 08:53:02 -0400 tytso@mit.edu 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@oracle.com>

Add more information about patch descriptions.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
---
 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.