From mboxrd@z Thu Jan  1 00:00:00 1970
From: Valdis.Kletnieks@vt.edu (Valdis.Kletnieks at vt.edu)
Date: Fri, 30 Sep 2016 03:52:53 -0400
Subject: [PATCH] INITEST: Documentation: Explains how INITEST works.
In-Reply-To: <87r3822ayp.fsf@miraculix.mork.no>
References: <1475212629-14976-1-git-send-email-free.amit.kumar@gmail.com>
	<87r3822ayp.fsf@miraculix.mork.no>
Message-ID: <37336.1475221973@turing-police.cc.vt.edu>
To: kernelnewbies@lists.kernelnewbies.org
List-Id: kernelnewbies.lists.kernelnewbies.org

On Fri, 30 Sep 2016 07:49:50 +0200, Bj?rn Mork said:

> 1) There should be *some* body text describing the patch, even for a very
>    basic change which is explained in full in subject.  This goes first
>    in the body, separated from the tags with a single empty line.

And to add to what he said:

Explaining the *why* is better than the *how*.

"Add Documentation/initest.txt" isn't that helpful - we can see from the diff
that's what it does.  "Add documentation explaining how to deal with the
Frobnizz  3000's wonky interrupts" is a lot better.

Similarly, "fix off-by-one error" is OK - but extending it to "fix off-by-one
error that causes the wireless card to select the wrong channel" is a lot better.

Sell us that patch - tell us *why* we want it in the kernel, and why we should
spend time reviewing it....

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 484 bytes
Desc: not available
Url : http://lists.kernelnewbies.org/pipermail/kernelnewbies/attachments/20160930/e9e4ebca/attachment.bin