linux-kernel - [PATCH] SubmittingPatches: add more about patch descriptions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Tue, 15 Jun 2010 09:15:58 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	tytso@....edu
Cc:	Tejun Heo <tj@...nel.org>,
	Andrew Morton <akpm@...ux-foundation.org>, mingo@...e.hu,
	awalls@...ix.net, linux-kernel@...r.kernel.org, jeff@...zik.org,
	rusty@...tcorp.com.au, cl@...ux-foundation.org,
	dhowells@...hat.com, arjan@...ux.intel.com,
	johannes@...solutions.net, oleg@...hat.com, axboe@...nel.dk
Subject: [PATCH] SubmittingPatches: add more about patch descriptions

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

Add more information about patch descriptions.

Signed-off-by: Randy Dunlap <randy.dunlap@...cle.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.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/