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>
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a830840..e6cbe59 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,14 +10,18 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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