mirror of
https://github.com/torvalds/linux.git
synced 2024-12-28 13:51:44 +00:00
Docs: Bring SubmittingPatches more into the git era
Much of the information in SubmittingPatches shows its pre-git history. Clean that up a bit and rephrase things with the assumption that developers will be using git. Also rewrite the "pull requests" section and include information on using signed tags. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet
parent
6de16eba62
commit
7994cc15d8
@ -24,13 +24,30 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE
|
||||
--------------------------------------------
|
||||
|
||||
|
||||
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
|
||||
@ -156,10 +173,15 @@ Example:
|
||||
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()")
|
||||
|
||||
@ -188,6 +210,12 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
@ -445,15 +473,15 @@ which appears in the changelog.
|
||||
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
|
||||
|
||||
@ -462,7 +490,7 @@ And here's what appears in 2.4 :
|
||||
[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.
|
||||
|
||||
|
||||
@ -558,6 +586,12 @@ method for indicating a bug fixed by the patch. See #2 above for more details.
|
||||
|
||||
|
||||
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:
|
||||
|
||||
@ -672,33 +706,57 @@ See more details on the proper patch format in the following
|
||||
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
|
||||
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
|
||||
|
||||
to get these changes:"
|
||||
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).
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
With rename detection, the statistics are rather different [...]
|
||||
because git will notice that a fair number of the changes are renames.
|
||||
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
|
||||
|
||||
|
||||
----------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user