Kernel/linux-stable
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git synced 2024-12-29 09:16:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Docs: SubmittingPatches: miscellaneous cleanups

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

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet 2014-12-23 08:54:36 -07:00
parent 0eea231437
commit d00c455964
1 changed files with 38 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
Documentation/SubmittingPatches
View File

@ -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