Docs: SubmittingPatches: miscellaneous cleanups

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

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

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-

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

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"

		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

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.

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

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.

------------------------------

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

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

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.

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

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