Documentation/SubmittingPatches: convert it to ReST markup
- Change the sections to use ReST markup; - Add cross-references where needed; - convert aspas to verbatim text; - use code block tags; - make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
ceeb1a5415
commit
5903019b2a
@ -1,9 +1,6 @@
|
||||
|
||||
How to Get Your Change Into the Linux Kernel
|
||||
or
|
||||
Care And Operation Of Your Linus Torvalds
|
||||
|
||||
|
||||
How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
|
||||
=========================================================================================
|
||||
|
||||
For a person or company who wishes to submit a change to the Linux
|
||||
kernel, the process can sometimes be daunting if you're not familiar
|
||||
@ -24,9 +21,8 @@ of the mechanical work done for you, though you'll still need to prepare
|
||||
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
|
||||
--------------------------------------------
|
||||
Creating and Sending your Change
|
||||
********************************
|
||||
|
||||
|
||||
0) Obtain a current source tree
|
||||
@ -34,35 +30,35 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE
|
||||
|
||||
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:
|
||||
which can be grabbed with::
|
||||
|
||||
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
||||
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
|
||||
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"
|
||||
------------
|
||||
1) ``diff -up``
|
||||
---------------
|
||||
|
||||
If you must generate your patches by hand, use "diff -up" or "diff -uprN"
|
||||
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
|
||||
in "unified diff" format, as supplied by the '-u' argument to diff(1).
|
||||
Also, please use the '-p' argument which shows which C function each
|
||||
in "unified diff" format, as supplied by the ``-u`` argument to diff(1).
|
||||
Also, please use the ``-p`` argument which shows which C function each
|
||||
change is in - that makes the resultant diff a lot easier to read.
|
||||
Patches should be based in the root kernel source directory,
|
||||
not in any lower subdirectory.
|
||||
|
||||
To create a patch for a single file, it is often sufficient to do:
|
||||
To create a patch for a single file, it is often sufficient to do::
|
||||
|
||||
SRCTREE= linux
|
||||
MYFILE= drivers/net/mydriver.c
|
||||
@ -75,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do:
|
||||
|
||||
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:
|
||||
own source tree. For example::
|
||||
|
||||
MYSRC= /devel/linux
|
||||
|
||||
@ -84,7 +80,7 @@ own source tree. For example:
|
||||
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
|
||||
``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.
|
||||
|
||||
@ -93,18 +89,18 @@ belong in a patch submission. Make sure to review your patch -after-
|
||||
generating it with diff(1), to ensure accuracy.
|
||||
|
||||
If your changes produce a lot of deltas, you need to split them into
|
||||
individual patches which modify things in logical stages; see section
|
||||
#3. This will facilitate review by other kernel developers,
|
||||
individual patches which modify things in logical stages; see
|
||||
:ref:`split_changes`. This will facilitate review by other kernel developers,
|
||||
very important if you want your patch accepted.
|
||||
|
||||
If you're using git, "git rebase -i" can help you with this process. If
|
||||
If you're using git, ``git rebase -i`` can help you with this process. If
|
||||
you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
|
||||
is another popular alternative.
|
||||
|
||||
.. _describe_changes:
|
||||
|
||||
|
||||
2) Describe your changes.
|
||||
-------------------------
|
||||
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
|
||||
@ -137,11 +133,11 @@ as you intend it to.
|
||||
|
||||
The maintainer will thank you if you write your patch description in a
|
||||
form which can be easily pulled into Linux's source code management
|
||||
system, git, as a "commit log". See #15, below.
|
||||
system, git, as a "commit log". See :ref:`explicit_in_reply_to`.
|
||||
|
||||
Solve only one problem per patch. If your description starts to get
|
||||
long, that's a sign that you probably need to split up your patch.
|
||||
See #3, next.
|
||||
See :ref:`split_changes`.
|
||||
|
||||
When you submit or resubmit a patch or patch series, include the
|
||||
complete patch description and justification for it. Don't just
|
||||
@ -171,7 +167,7 @@ patch as submitted.
|
||||
If you want to refer to a specific commit, don't just refer to the
|
||||
SHA-1 ID of the commit. Please also include the oneline summary of
|
||||
the commit, to make it easier for reviewers to know what it is about.
|
||||
Example:
|
||||
Example::
|
||||
|
||||
Commit e21d2170f36602ae2708 ("video: remove unnecessary
|
||||
platform_set_drvdata()") removed the unnecessary
|
||||
@ -186,22 +182,24 @@ 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. For example:
|
||||
SHA-1 ID, and the one line summary. For example::
|
||||
|
||||
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
|
||||
|
||||
The following git-config settings can be used to add a pretty format for
|
||||
outputting the above style in the git log or git show commands
|
||||
outputting the above style in the git log or git show commands::
|
||||
|
||||
[core]
|
||||
abbrev = 12
|
||||
[pretty]
|
||||
fixes = Fixes: %h (\"%s\")
|
||||
|
||||
3) Separate your changes.
|
||||
-------------------------
|
||||
.. _split_changes:
|
||||
|
||||
Separate each _logical change_ into a separate patch.
|
||||
3) Separate your changes
|
||||
------------------------
|
||||
|
||||
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
|
||||
@ -217,12 +215,12 @@ 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"
|
||||
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
|
||||
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.
|
||||
|
||||
@ -231,8 +229,8 @@ then only post say 15 or so at a time and wait for review and integration.
|
||||
|
||||
|
||||
|
||||
4) Style-check your changes.
|
||||
----------------------------
|
||||
4) Style-check your changes
|
||||
---------------------------
|
||||
|
||||
Check your patch for basic style violations, details of which can be
|
||||
found in Documentation/CodingStyle. Failure to do so simply wastes
|
||||
@ -260,8 +258,8 @@ You should be able to justify all violations that remain in your
|
||||
patch.
|
||||
|
||||
|
||||
5) Select the recipients for your patch.
|
||||
----------------------------------------
|
||||
5) Select the recipients for your patch
|
||||
---------------------------------------
|
||||
|
||||
You should always copy the appropriate subsystem maintainer(s) on any patch
|
||||
to code that they maintain; look through the MAINTAINERS file and the
|
||||
@ -295,7 +293,7 @@ to allow distributors to get the patch out to users; in such cases,
|
||||
obviously, the patch should not be sent to any public lists.
|
||||
|
||||
Patches that fix a severe bug in a released kernel should be directed
|
||||
toward the stable maintainers by putting a line like this:
|
||||
toward the stable maintainers by putting a line like this::
|
||||
|
||||
Cc: stable@vger.kernel.org
|
||||
|
||||
@ -312,12 +310,14 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES
|
||||
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
|
||||
least a notification of the change, so that some information makes its way
|
||||
into the manual pages. User-space API changes should also be copied to
|
||||
linux-api@vger.kernel.org.
|
||||
linux-api@vger.kernel.org.
|
||||
|
||||
For small patches you may want to CC the Trivial Patch Monkey
|
||||
trivial@kernel.org which collects "trivial" patches. Have a look
|
||||
into the MAINTAINERS file for its current manager.
|
||||
|
||||
Trivial patches must qualify for one of the following rules:
|
||||
|
||||
Spelling fixes in documentation
|
||||
Spelling fixes for errors which could break grep(1)
|
||||
Warning fixes (cluttering with useless warnings is bad)
|
||||
@ -332,8 +332,8 @@ Trivial patches must qualify for one of the following rules:
|
||||
|
||||
|
||||
|
||||
6) No MIME, no links, no compression, no attachments. Just plain text.
|
||||
-----------------------------------------------------------------------
|
||||
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
|
||||
@ -356,8 +356,8 @@ you to re-send them using MIME.
|
||||
See Documentation/email-clients.txt for hints about configuring
|
||||
your e-mail client so that it sends your patches untouched.
|
||||
|
||||
7) E-mail size.
|
||||
---------------
|
||||
7) E-mail size
|
||||
--------------
|
||||
|
||||
Large changes are not appropriate for mailing lists, and some
|
||||
maintainers. If your patch, uncompressed, exceeds 300 kB in size,
|
||||
@ -366,8 +366,8 @@ 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.
|
||||
------------------------------
|
||||
8) Respond to review comments
|
||||
-----------------------------
|
||||
|
||||
Your patch will almost certainly get comments from reviewers on ways in
|
||||
which the patch can be improved. You must respond to those comments;
|
||||
@ -382,8 +382,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond
|
||||
politely and address the problems they have pointed out.
|
||||
|
||||
|
||||
9) Don't get discouraged - or impatient.
|
||||
----------------------------------------
|
||||
9) Don't get discouraged - or impatient
|
||||
---------------------------------------
|
||||
|
||||
After you have submitted your change, be patient and wait. Reviewers are
|
||||
busy people and may not get to your patch right away.
|
||||
@ -419,9 +419,10 @@ patch, which certifies that you wrote it or otherwise have the right to
|
||||
pass it on as an open-source patch. The rules are pretty simple: if you
|
||||
can certify the below:
|
||||
|
||||
Developer's Certificate of Origin 1.1
|
||||
Developer's Certificate of Origin 1.1
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By making a contribution to this project, I certify that:
|
||||
By making a contribution to this project, I certify that:
|
||||
|
||||
(a) The contribution was created in whole or in part by me and I
|
||||
have the right to submit it under the open source license
|
||||
@ -445,7 +446,7 @@ can certify the below:
|
||||
maintained indefinitely and may be redistributed consistent with
|
||||
this project or the open source license(s) involved.
|
||||
|
||||
then you just add a line saying
|
||||
then you just add a line saying::
|
||||
|
||||
Signed-off-by: Random J Developer <random@developer.example.org>
|
||||
|
||||
@ -466,7 +467,7 @@ you add a line between the last Signed-off-by header and yours, indicating
|
||||
the nature of your changes. While there is nothing mandatory about this, it
|
||||
seems like prepending the description with your mail and/or name, all
|
||||
enclosed in square brackets, is noticeable enough to make it obvious that
|
||||
you are responsible for last-minute changes. Example :
|
||||
you are responsible for last-minute changes. Example::
|
||||
|
||||
Signed-off-by: Random J Developer <random@developer.example.org>
|
||||
[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
|
||||
@ -481,15 +482,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 a 3.x-stable release:
|
||||
here's what we see in a 3.x-stable release::
|
||||
|
||||
Date: Tue Oct 7 07:26:38 2014 -0400
|
||||
Date: Tue Oct 7 07:26:38 2014 -0400
|
||||
|
||||
libata: Un-break ATA blacklist
|
||||
|
||||
commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
|
||||
|
||||
And here's what might appear in an older kernel once a patch is backported:
|
||||
And here's what might appear in an older kernel once a patch is backported::
|
||||
|
||||
Date: Tue May 13 22:12:27 2008 +0200
|
||||
|
||||
@ -529,7 +530,7 @@ When in doubt people should refer to the original discussion in the mailing
|
||||
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.
|
||||
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 - but it should indicate that this person was copied on the
|
||||
patch. This tag documents that potentially interested parties
|
||||
@ -552,11 +553,12 @@ future patches, and ensures credit for the testers.
|
||||
Reviewed-by:, instead, indicates that the patch has been reviewed and found
|
||||
acceptable according to the Reviewer's Statement:
|
||||
|
||||
Reviewer's statement of oversight
|
||||
Reviewer's statement of oversight
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By offering my Reviewed-by: tag, I state that:
|
||||
By offering my Reviewed-by: tag, I state that:
|
||||
|
||||
(a) I have carried out a technical review of this patch to
|
||||
(a) I have carried out a technical review of this patch to
|
||||
evaluate its appropriateness and readiness for inclusion into
|
||||
the mainline kernel.
|
||||
|
||||
@ -594,7 +596,8 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
|
||||
is used to make it easy to determine where a bug originated, which can help
|
||||
review a bug fix. This tag also assists the stable kernel team in determining
|
||||
which stable kernel versions should receive your fix. This is the preferred
|
||||
method for indicating a bug fixed by the patch. See #2 above for more details.
|
||||
method for indicating a bug fixed by the patch. See :ref:`describe_changes`
|
||||
for more details.
|
||||
|
||||
|
||||
14) The canonical patch format
|
||||
@ -602,16 +605,16 @@ method for indicating a bug fixed by the patch. See #2 above for more details.
|
||||
|
||||
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
|
||||
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:
|
||||
The canonical patch subject line is::
|
||||
|
||||
Subject: [PATCH 001/123] subsystem: summary phrase
|
||||
|
||||
The canonical patch message body contains the following:
|
||||
|
||||
- A "from" line specifying the patch author (only needed if the person
|
||||
- A ``from`` line specifying the patch author (only needed if the person
|
||||
sending the patch is not the author).
|
||||
|
||||
- An empty line.
|
||||
@ -619,10 +622,10 @@ The canonical patch message body contains the following:
|
||||
- The body of the explanation, line wrapped at 75 columns, which will
|
||||
be copied to the permanent changelog to describe this patch.
|
||||
|
||||
- The "Signed-off-by:" lines, described above, which will
|
||||
- The ``Signed-off-by:`` lines, described above, which will
|
||||
also go in the changelog.
|
||||
|
||||
- A marker line containing simply "---".
|
||||
- A marker line containing simply ``---``.
|
||||
|
||||
- Any additional comments not suitable for the changelog.
|
||||
|
||||
@ -633,32 +636,32 @@ alphabetically by subject line - pretty much any email reader will
|
||||
support that - since because the sequence number is zero-padded,
|
||||
the numerical and alphabetic sort is the same.
|
||||
|
||||
The "subsystem" in the email's Subject should identify which
|
||||
The ``subsystem`` in the email's Subject should identify which
|
||||
area or subsystem of the kernel is being patched.
|
||||
|
||||
The "summary phrase" in the email's Subject should concisely
|
||||
describe the patch which that email contains. The "summary
|
||||
phrase" should not be a filename. Do not use the same "summary
|
||||
phrase" for every patch in a whole patch series (where a "patch
|
||||
series" is an ordered sequence of multiple, related patches).
|
||||
The ``summary phrase`` in the email's Subject should concisely
|
||||
describe the patch which that email contains. The ``summary
|
||||
phrase`` should not be a filename. Do not use the same ``summary
|
||||
phrase`` for every patch in a whole patch series (where a ``patch
|
||||
series`` is an ordered sequence of multiple, related patches).
|
||||
|
||||
Bear in mind that the "summary phrase" of your email becomes a
|
||||
Bear in mind that the ``summary phrase`` of your email becomes a
|
||||
globally-unique identifier for that patch. It propagates all the way
|
||||
into the git changelog. The "summary phrase" may later be used in
|
||||
into the git changelog. The ``summary phrase`` may later be used in
|
||||
developer discussions which refer to the patch. People will want to
|
||||
google for the "summary phrase" to read discussion regarding that
|
||||
google for the ``summary phrase`` to read discussion regarding that
|
||||
patch. It will also be the only thing that people may quickly see
|
||||
when, two or three months later, they are going through perhaps
|
||||
thousands of patches using tools such as "gitk" or "git log
|
||||
thousands of patches using tools such as ``gitk`` or "git log
|
||||
--oneline".
|
||||
|
||||
For these reasons, the "summary" must be no more than 70-75
|
||||
For these reasons, the ``summary`` must be no more than 70-75
|
||||
characters, and it must describe both what the patch changes, as well
|
||||
as why the patch might be necessary. It is challenging to be both
|
||||
succinct and descriptive, but that is what a well-written summary
|
||||
should do.
|
||||
|
||||
The "summary phrase" may be prefixed by tags enclosed in square
|
||||
The ``summary phrase`` may be prefixed by tags enclosed in square
|
||||
brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
|
||||
not considered part of the summary phrase, but describe how the patch
|
||||
should be treated. Common tags might include a version descriptor if
|
||||
@ -670,19 +673,19 @@ that developers understand the order in which the patches should be
|
||||
applied and that they have reviewed or applied all of the patches in
|
||||
the patch series.
|
||||
|
||||
A couple of example Subjects:
|
||||
A couple of example Subjects::
|
||||
|
||||
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
|
||||
Subject: [PATCH v2 01/27] x86: fix eflags tracking
|
||||
|
||||
The "from" line must be the very first line in the message body,
|
||||
The ``from`` line must be the very first line in the message body,
|
||||
and has the form:
|
||||
|
||||
From: Original Author <author@example.com>
|
||||
|
||||
The "from" line specifies who will be credited as the author of the
|
||||
patch in the permanent changelog. If the "from" line is missing,
|
||||
then the "From:" line from the email header will be used to determine
|
||||
The ``from`` line specifies who will be credited as the author of the
|
||||
patch in the permanent changelog. If the ``from`` line is missing,
|
||||
then the ``From:`` line from the email header will be used to determine
|
||||
the patch author in the changelog.
|
||||
|
||||
The explanation body will be committed to the permanent source
|
||||
@ -694,23 +697,23 @@ especially useful for people who might be searching the commit logs
|
||||
looking for the applicable patch. If a patch fixes a compile failure,
|
||||
it may not be necessary to include _all_ of the compile failures; just
|
||||
enough that it is likely that someone searching for the patch can find
|
||||
it. As in the "summary phrase", it is important to be both succinct as
|
||||
it. As in the ``summary phrase``, it is important to be both succinct as
|
||||
well as descriptive.
|
||||
|
||||
The "---" marker line serves the essential purpose of marking for patch
|
||||
The ``---`` marker line serves the essential purpose of marking for patch
|
||||
handling tools where the changelog message ends.
|
||||
|
||||
One good use for the additional comments after the "---" marker is for
|
||||
One good use for the additional comments after the ``---`` marker is for
|
||||
a diffstat, to show what files have changed, and the number of
|
||||
inserted and deleted lines per file. A diffstat is especially useful
|
||||
on bigger patches. Other comments relevant only to the moment or the
|
||||
maintainer, not suitable for the permanent changelog, should also go
|
||||
here. A good example of such comments might be "patch changelogs"
|
||||
here. A good example of such comments might be ``patch changelogs``
|
||||
which describe what has changed between the v1 and v2 version of the
|
||||
patch.
|
||||
|
||||
If you are going to include a diffstat after the "---" marker, please
|
||||
use diffstat options "-p 1 -w 70" so that filenames are listed from
|
||||
If you are going to include a diffstat after the ``---`` marker, please
|
||||
use diffstat options ``-p 1 -w 70`` so that filenames are listed from
|
||||
the top of the kernel source tree and don't use too much horizontal
|
||||
space (easily fit in 80 columns, maybe with some indentation). (git
|
||||
generates appropriate diffstats by default.)
|
||||
@ -718,11 +721,13 @@ generates appropriate diffstats by default.)
|
||||
See more details on the proper patch format in the following
|
||||
references.
|
||||
|
||||
.. _explicit_in_reply_to:
|
||||
|
||||
15) Explicit In-Reply-To headers
|
||||
--------------------------------
|
||||
|
||||
It can be helpful to manually add In-Reply-To: headers to a patch
|
||||
(e.g., when using "git send-email") to associate the patch with
|
||||
(e.g., when using ``git send-email``) to associate the patch with
|
||||
previous relevant discussion, e.g. to link a bug fix to the email with
|
||||
the bug report. However, for a multi-patch series, it is generally
|
||||
best to avoid using In-Reply-To: to link to older versions of the
|
||||
@ -732,12 +737,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
|
||||
the cover email text) to link to an earlier version of the patch series.
|
||||
|
||||
|
||||
16) Sending "git pull" requests
|
||||
-------------------------------
|
||||
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
|
||||
``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. If in doubt you can use
|
||||
@ -746,7 +751,7 @@ series, giving the maintainer the option of using either.
|
||||
|
||||
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:
|
||||
interest on a single line; it should look something like::
|
||||
|
||||
Please pull from
|
||||
|
||||
@ -755,10 +760,10 @@ interest on a single line; it should look something like:
|
||||
to get these changes:
|
||||
|
||||
A pull request should also include an overall message saying what will be
|
||||
included in the request, a "git shortlog" listing of the patches
|
||||
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 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
|
||||
@ -771,7 +776,7 @@ 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
|
||||
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
|
||||
@ -782,14 +787,13 @@ 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:
|
||||
command like this will do the trick::
|
||||
|
||||
git request-pull master git://my.public.tree/linux.git my-signed-tag
|
||||
|
||||
|
||||
----------------------
|
||||
SECTION 2 - REFERENCES
|
||||
----------------------
|
||||
REFERENCES
|
||||
**********
|
||||
|
||||
Andrew Morton, "The perfect patch" (tpp).
|
||||
<http://www.ozlabs.org/~akpm/stuff/tpp.txt>
|
||||
@ -818,4 +822,3 @@ Andi Kleen, "On submitting kernel patches"
|
||||
Some strategies to get difficult or controversial changes in.
|
||||
http://halobates.de/on-submitting-patches.pdf
|
||||
|
||||
--
|
||||
|
||||
Loading…
Reference in New Issue
Block a user