Docs: Bring SubmittingPatches more into the git era

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

0) Obtain a current source tree

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

If you do not have a repository with the current kernel source handy, use

git to obtain one.  You'll want to start with the mainline repository,

which can be grabbed with:

  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 

Note, however, that you may not want to develop against the mainline tree

directly.  Most subsystem maintainers run their own trees and want to see

patches prepared against those trees.  See the "T:" entry for the subsystem

in the MAINTAINERS file to find that tree, or simply ask the maintainer if

the tree is not listed there.

It is still possible to download kernel releases via tarballs (as described

in the next section), but that is the hard way to do kernel development.

1) "diff -up"

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

Use "diff -up" or "diff -uprN" to create patches.  git generates patches

in this form by default; if you're using git, you can skip this section

entirely.

If you must generate your patches by hand, use "diff -up" or "diff -uprN"

to create patches.  Git generates patches in this form by default; if

you're using git, you can skip this section entirely.

All changes to the Linux kernel occur in the form of patches, as

generated by diff(1).  When creating your patch, make sure to create it

	platform_set_drvdata(), but left the variable "dev" unused,

	delete it.

You should also be sure to use at least the first twelve characters of the

SHA-1 ID.  The kernel repository holds a *lot* of objects, making

collisions with shorter IDs a real possibility.  Bear in mind that, even if

there is no collision with your six-character ID now, that condition may

change five years from now.

If your patch fixes a bug in a specific commit, e.g. you found an issue using

git-bisect, please use the 'Fixes:' tag with the first 12 characters of the

SHA-1 ID, and the one line summary.

Example:

SHA-1 ID, and the one line summary.  For example:

	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")

complete, that is OK.  Simply note "this patch depends on patch X"

in your patch description.

When dividing your change into a series of patches, take special care to

ensure that the kernel builds and runs properly after each patch in the

series.  Developers using "git bisect" to track down a problem can end up

splitting your patch series at any point; they will not thank you if you

introduce bugs in the middle.

If you cannot condense your patch set into a smaller set of patches,

then only post say 15 or so at a time and wait for review and integration.

Special note to back-porters: It seems to be a common and useful practice

to insert an indication of the origin of a patch at the top of the commit

message (just after the subject line) to facilitate tracking. For instance,

here's what we see in 2.6-stable :

here's what we see in a 3.x-stable release:

    Date:   Tue May 13 19:10:30 2008 +0000

Date:   Tue Oct 7 07:26:38 2014 -0400

        SCSI: libiscsi regression in 2.6.25: fix nop timer handling

    libata: Un-break ATA blacklist

        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream

    commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.

And here's what appears in 2.4 :

And here's what might appear in an older kernel once a patch is backported:

    Date:   Tue May 13 22:12:27 2008 +0200

        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]

Whatever the format, this information provides a valuable help to people

tracking your trees, and to people trying to trouble-shoot bugs in your

tracking your trees, and to people trying to troubleshoot bugs in your

tree.

15) The canonical patch format

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

This section describes how the patch itself should be formatted.  Note

that, if you have your patches stored in a git repository, proper patch

formatting can be had with "git format-patch".  The tools cannot create

the necessary text, though, so read the instructions below anyway.

The canonical patch subject line is:

references.

16) Sending "git pull" requests  (from Linus emails)

16) Sending "git pull" requests

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

Please write the git repo address and branch name alone on the same line

so that I can't even by mistake pull from the wrong branch, and so

that a triple-click just selects the whole thing.

If you have a series of patches, it may be most convenient to have the

maintainer pull them directly into the subsystem repository with a

"git pull" operation.  Note, however, that pulling patches from a developer

requires a higher degree of trust than taking patches from a mailing list.

As a result, many subsystem maintainers are reluctant to take pull

requests, especially from new, unknown developers.

So the proper format is something along the lines of:

A pull request should have [GIT] or [PULL] in the subject line.  The

request itself should include the repository name and the branch of

interest on a single line; it should look something like:

	"Please pull from

  Please pull from

      git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus

  to get these changes:"

so that I don't have to hunt-and-peck for the address and inevitably

get it wrong (actually, I've only gotten it wrong a few times, and

checking against the diffstat tells me when I get it wrong, but I'm

just a lot more comfortable when I don't have to "look for" the right

thing to pull, and double-check that I have the right branch-name).

Please use "git diff -M --stat --summary" to generate the diffstat:

the -M enables rename detection, and the summary enables a summary of

new/deleted or renamed files.

With rename detection, the statistics are rather different [...]

because git will notice that a fair number of the changes are renames.

A pull request should also include an overall message saying what will be

included in the request, a "git shortlog" listing of the patches

themselves, and a diffstat showing the overall effect of the patch series.

The easiest way to get all this information together is, of course, to let

git do it for you with the "git request-pull" command.

Some maintainers (including Linus) want to see pull requests from signed

commits; that increases their confidence that the request actually came

from you.  Linus, in particular, will not pull from public hosting sites

like GitHub in the absence of a signed tag.

The first step toward creating such tags is to make a GNUPG key and get it

signed by one or more core kernel developers.  This step can be hard for

new developers, but there is no way around it.  Attending conferences can

be a good way to find developers who can sign your key.

Once you have prepared a patch series in git that you wish to have somebody

pull, create a signed tag with "git tag -s".  This will create a new tag

identifying the last commit in the series and containing a signature

created with your private key.  You will also have the opportunity to add a

changelog-style message to the tag; this is an ideal place to describe the

effects of the pull request as a whole.

If the tree the maintainer will be pulling from is not the repository you

are working from, don't forget to push the signed tag explicitly to the

public tree.

When generating your pull request, use the signed tag as the target.  A

command like this will do the trick:

  git request-pull master git://my.public.tree/linux.git my-signed-tag

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