mirror of
https://github.com/torvalds/linux.git
synced 2024-12-28 13:51:44 +00:00
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>
This commit is contained in:
Jonathan Corbet
parent
0eea231437
commit
d00c455964
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user