[PATCH] HOWTO fixes from kay

1 files changed, 40 insertions, 10 deletions

diff --git a/HOWTO b/HOWTO
index 8e4ed6bcf83b7..f69f9c14e6012 100644
--- a/HOWTO
+++ b/HOWTO
@@ -19,7 +19,6 @@ know to achieve this by describing the process you need to go through,
 and hints on how to work with the community.  It will also try to
 explain some of the reasons why the community works like it does.
 
-
 The kernel is written mostly in C, with some architectural-dependent
 parts written in assembly. A good understanding of C is required to
 kernel development. Assembly (any architecture) is not required unless
@@ -27,7 +26,7 @@ you plan to do low-level development for that architecture. Though they
 are not a good substitute for a solid C education and/or years of
 experience, the following books are good, if anything for reference:
 
-"The C Programming Language" by Kernhigan and Ritchie [Prentice Hall]
+"The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
 "Practical C Programming" by Steve Oualline [O'Reilly]
 "Programming the 80386" by Crawford and Gelsinger [Sybek]
 "UNIX Systems for Modern Architectures" by Curt Schimmel [Addison Wesley]
@@ -42,7 +41,7 @@ some information on them."
 
 Please remember that you are trying to learn how to work with the
 existing development community.  It is a very diverse group of people,
-with very high standards for coding, style, and procedure.  These
+with very high standards for coding, style and procedure.  These
 procedures have been created over time based on what they have found to
 work best for such a large and geographically dispursed team.  Try to
 learn as much as possible about these procedures ahead of time, as they
@@ -71,7 +70,7 @@ is a list of files that are in the kernel source tree that are required
 reading:
   Documetation/CodingStyle
     This describes the Linux kernel coding style, and some of the
-    rational behind it.  The main point here is that we have a coding
+    rationale behind it.  The main point here is that we have a coding
     style, and you can not ignore it.
 
   Documentation/SubmittingPatches
@@ -84,7 +83,7 @@ reading:
     these rules, the odds of your patch being accepted are very low.
 
   Documentation/stable_api_nonsense.txt
-    This file describes the rational behind why the Linux kernel does
+    This file describes the rationale behind why the Linux kernel does
     not have a stable in-kernel api.  If you want to try to come up with
     a shim-layer for some subsystem, in order to make it easier to adapt
     your existing code to Linux, or to try to mitigate the rapid change
@@ -176,8 +175,10 @@ developers participate on the Linux Kernel Mailing list.  Details on how
 to subscribe and unsubscribe from the list, can be found at:
 	http://vger.kernel.org/vger-lists.html#linux-kernel
 There are archives of the mailing list on the web in many different
-places.  Please use a search engine to find these archives if you wish
-to research what has been discussed in the past.
+places.  Use a search engine to find these archives. It is highly
+recommended that you search the archives about the topic you want to bring
+up, before you post it to the list. A lot of things are already discussed
+in detail and are only recorded at the mailing list archives.
 
 Most of the individual kernel subsystems also have their own separate
 mailing list where they do their development efforts.  See the
@@ -193,6 +194,26 @@ Though a bit cheesy, the following URL has some simple guidelines for
 interacting with the list (or any list):
 	http://www.albion.com/netiquette/
 
+If multiple people respond to your mail, the CC: list of recipients may
+get pretty large. Don't remove anybody from the CC: list without a good
+reason, or don't reply only to the list address. Get used to receive the
+mail twice, one from the sender and the one from the list and don't try
+to tune that by adding fancy mail-headers, people will not like it.
+
+Remember to keep the context and the attribution of your replies intact,
+keep the "John Kernelhacker wrote ...:" lines at the top of you reply and
+add your statements between the individual quoted sections instead of
+writing at the top of the mail.
+
+If you add patches to your mail, make sure they are plain readable text
+as stated in Documentation/SubmittingPatches. Kernel developers don't
+want to deal with attachements or compressed patches, they may want
+to comment individual lines of your patch, which works only that way.
+Make sure you use a mail program that does not mangle spaces and tab
+characters. A good first test is to send the mail to yourself and try
+to apply your own patch by yourself. If that doesn't work, get your
+mail program fixed or change it until it works.
+
 Above all, please remember to show respect to other subscribers.
 
 
@@ -221,6 +242,8 @@ do to try to avoid problems:
     - "Here is my 1000 page design document that describes my idea"
     - "I've been working on this for 6 months..."
     - "Here's a 5000 line patch that..."
+    - "I rewrote all of the current mess, and here it is ..."
+    - "I have a deadline, until that patch needs to be applied."
 
 Another way the kernel community is different than most traditional
 software engineering work environments is the faceless nature of
@@ -270,14 +293,21 @@ The reasons for breaking things up are the following:
 Think of a teacher grading homework from a math student.  The teacher
 does not want to see the student's trials and errors before they came up
 with the solution. They want to see the cleanest, most elegant answer.
-The student knows this, and would never submit her intermediate work
+A good student knows this, and would never submit her intermediate work
 before the final solution.
 
 The same is true of kernel development. The maintainers and reviewers do
 not want to see the thought process behind the solution to the problem
-one is solving. They want to see a final, simple, elegant solution.
+one is solving. They want to see a simple and elegant solution.
+
+That may be challenging to keep the balance between presenting an elegant
+solution and working together with the community and discuss your
+unfinished work. Therefore it is good to get early in the process to
+get feedback to improve your work, but also keep your changes in small
+chunks that they may get already accepted, even when your whole task is
+not ready for inclusion now.
 
-Both of these things are sometimes very hard to do. It can take years
+These things are sometimes very hard to do. It can take years
 to perfect these practices (if at all). It's a continuous process of
 improvement that requires a lot of patience and determination. But,
 don't give up. It's possible. Many have done it before, and each had to