提交 7994cc15 编写于 作者: J Jonathan Corbet

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: NJonathan Corbet <corbet@lwn.net>
上级 6de16eba
......@@ -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
-------------------------------
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.
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 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.
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
So the proper format is something along the lines of:
to get these changes:"
"Please pull from
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.
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
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.
to get these changes:"
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.
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).
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.
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.
When generating your pull request, use the signed tag as the target. A
command like this will do the trick:
With rename detection, the statistics are rather different [...]
because git will notice that a fair number of the changes are renames.
git request-pull master git://my.public.tree/linux.git my-signed-tag
----------------------
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册