Docs: SubmittingPatches: miscellaneous cleanups

Changes to make the formatting a bit more consistent and fix up wording in
various places.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

1 files changed, 38 insertions, 23 deletions

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a8308401a048..e6cbe59d890f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,14 +10,18 @@ kernel, the process can sometimes be daunting if you're not familiar
 with "the system."  This text is a collection of suggestions which
 can greatly increase the chances of your change being accepted.
 
-Read Documentation/SubmitChecklist for a list of items to check
-before submitting code.  If you are submitting a driver, also read
+This document contains a large number of suggestions in a relatively terse
+format.  For detailed information on how the kernel development process
+works, see Documentation/development-process.  Also, read
+Documentation/SubmitChecklist for a list of items to check before
+submitting code.  If you are submitting a driver, also read
 Documentation/SubmittingDrivers.
 
 Many of these steps describe the default behavior of the git version
 control system; if you use git to prepare your patches, you'll find much
 of the mechanical work done for you, though you'll still need to prepare
-and document a sensible set of patches.
+and document a sensible set of patches.  In general, use of git will make
+your life as a kernel developer easier.
 
 --------------------------------------------
 SECTION 1 - CREATING AND SENDING YOUR CHANGE
@@ -59,7 +63,7 @@ not in any lower subdirectory.
 
 To create a patch for a single file, it is often sufficient to do:
 
-        SRCTREE= linux-2.6
+        SRCTREE= linux
         MYFILE=  drivers/net/mydriver.c
 
         cd $SRCTREE
@@ -72,17 +76,16 @@ To create a patch for multiple files, you should unpack a "vanilla",
 or unmodified kernel source tree, and generate a diff against your
 own source tree.  For example:
 
-        MYSRC= /devel/linux-2.6
+        MYSRC= /devel/linux
 
-        tar xvfz linux-2.6.12.tar.gz
-        mv linux-2.6.12 linux-2.6.12-vanilla
-        diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
-                linux-2.6.12-vanilla $MYSRC > /tmp/patch
+        tar xvfz linux-3.19.tar.gz
+        mv linux-3.19 linux-3.19-vanilla
+        diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
+                linux-3.19-vanilla $MYSRC > /tmp/patch
 
 "dontdiff" is a list of files which are generated by the kernel during
 the build process, and should be ignored in any diff(1)-generated
-patch.  The "dontdiff" file is included in the kernel tree in
-2.6.12 and later.
+patch.
 
 Make sure your patch does not include any extra files which do not
 belong in a patch submission.  Make sure to review your patch -after-
@@ -100,6 +103,7 @@ is another popular alternative.
 
 
 2) Describe your changes.
+-------------------------
 
 Describe your problem.  Whether your patch is a one-line bug fix or
 5000 lines of a new feature, there must be an underlying problem that
@@ -141,10 +145,10 @@ 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
+subsystem maintainer 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
+This benefits both the maintainers and reviewers.  Some reviewers
 probably didn't even receive earlier versions of the patch.
 
 Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
@@ -194,8 +198,9 @@ outputting the above style in the git log or git show commands
                 fixes = Fixes: %h (\"%s\")
 
 3) Separate your changes.
+-------------------------
 
-Separate _logical changes_ into a single patch file.
+Separate each _logical change_ into a separate patch.
 
 For example, if your changes include both bug fixes and performance
 enhancements for a single driver, separate those changes into two
@@ -206,6 +211,10 @@ On the other hand, if you make a single change to numerous files,
 group those changes into a single patch.  Thus a single logical change
 is contained within a single patch.
 
+The point to remember is that each patch should make an easily understood
+change that can be verified by reviewers.  Each patch should be justifiable
+on its own merits.
+
 If one patch depends on another patch in order for a change to be
 complete, that is OK.  Simply note "this patch depends on patch X"
 in your patch description.
@@ -321,6 +330,7 @@ Trivial patches must qualify for one of the following rules:
 
 
 6) No MIME, no links, no compression, no attachments.  Just plain text.
+-----------------------------------------------------------------------
 
 Linus and other kernel developers need to be able to read and comment
 on the changes you are submitting.  It is important for a kernel
@@ -344,15 +354,14 @@ See Documentation/email-clients.txt for hints about configuring
 your e-mail client so that it sends your patches untouched.
 
 7) E-mail size.
-
-When sending patches to Linus, always follow step #7.
+---------------
 
 Large changes are not appropriate for mailing lists, and some
 maintainers.  If your patch, uncompressed, exceeds 300 kB in size,
 it is preferred that you store your patch on an Internet-accessible
-server, and provide instead a URL (link) pointing to your patch.
-
-
+server, and provide instead a URL (link) pointing to your patch.  But note
+that if your patch exceeds 300 kB, it almost certainly needs to be broken up
+anyway.
 
 8) Respond to review comments.
 ------------------------------
@@ -385,6 +394,7 @@ busy times like merge windows.
 
 
 10) Include PATCH in the subject
+--------------------------------
 
 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
 convention to prefix your subject line with [PATCH].  This lets Linus
@@ -394,6 +404,7 @@ e-mail discussions.
 
 
 11) Sign your work
+------------------
 
 To improve tracking of who did what, especially with patches that can
 percolate to their final resting place in the kernel through several
@@ -489,13 +500,14 @@ tree.
 
 
 12) When to use Acked-by: and Cc:
+---------------------------------
 
 The Signed-off-by: tag indicates that the signer was involved in the
 development of the patch, or that he/she was in the patch's delivery path.
 
 If a person was not directly involved in the preparation or handling of a
 patch but wishes to signify and record their approval of it then they can
-arrange to have an Acked-by: line added to the patch's changelog.
+ask to have an Acked-by: line added to the patch's changelog.
 
 Acked-by: is often used by the maintainer of the affected code when that
 maintainer neither contributed to nor forwarded the patch.
@@ -503,7 +515,8 @@ maintainer neither contributed to nor forwarded the patch.
 Acked-by: is not as formal as Signed-off-by:.  It is a record that the acker
 has at least reviewed the patch and has indicated acceptance.  Hence patch
 mergers will sometimes manually convert an acker's "yep, looks good to me"
-into an Acked-by:.
+into an Acked-by: (but note that it is usually better to ask for an
+explicit ack).
 
 Acked-by: does not necessarily indicate acknowledgement of the entire patch.
 For example, if a patch affects multiple subsystems and has an Acked-by: from
@@ -515,11 +528,13 @@ list archives.
 If a person has had the opportunity to comment on a patch, but has not
 provided such comments, you may optionally add a "Cc:" tag to the patch.
 This is the only tag which might be added without an explicit action by the
-person it names.  This tag documents that potentially interested parties
-have been included in the discussion
+person it names - but it should indicate that this person was copied on the
+patch.  This tag documents that potentially interested parties
+have been included in the discussion.
 
 
 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
+--------------------------------------------------------------------------
 
 The Reported-by tag gives credit to people who find bugs and report them and it
 hopefully inspires them to help us again in the future.  Please note that if