submitting-patches.rst: presume git will be used
Git is fairly ubiquitous these days, and the additional information in this documentation for preparing patches without it is not especially relevant anymore and may serve to confuse new contributors. The git request-pull comments were also removed, given that it is not a tool well-suited to novice contributors, nor do maintainers especially appreciate receiving unexpected request-pulls from new contributors. Signed-off-by: Drew DeVault <sir@cmpwn.com> Link: https://lore.kernel.org/r/20200903160545.83185-5-sir@cmpwn.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Drew DeVault
Jonathan Corbet
parent
4ebdf7be21
commit
9f364b605f
|
|
@ -18,11 +18,10 @@ submitting code. If you are submitting a driver, also read
|
|||
for device tree binding patches, read
|
||||
Documentation/devicetree/bindings/submitting-patches.rst.
|
||||
|
||||
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. In general, use of ``git`` will make
|
||||
your life as a kernel developer easier.
|
||||
This documentation assumes that you're using ``git`` to prepare your patches.
|
||||
If you're unfamiliar with ``git``, you would be well-advised to learn how to
|
||||
use it, it will make your life as a kernel developer and in general much
|
||||
easier.
|
||||
|
||||
Obtain a current source tree
|
||||
----------------------------
|
||||
|
|
@ -39,64 +38,6 @@ 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``
|
||||
---------------
|
||||
|
||||
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 :manpage:`diff(1)`. When creating your patch, make sure to
|
||||
create it in "unified diff" format, as supplied by the ``-u`` argument
|
||||
to :manpage:`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::
|
||||
|
||||
SRCTREE=linux
|
||||
MYFILE=drivers/net/mydriver.c
|
||||
|
||||
cd $SRCTREE
|
||||
cp $MYFILE $MYFILE.orig
|
||||
vi $MYFILE # make your change
|
||||
cd ..
|
||||
diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
|
||||
|
||||
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::
|
||||
|
||||
MYSRC=/devel/linux
|
||||
|
||||
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 :manpage:`diff(1)`-generated
|
||||
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-
|
||||
generating it with :manpage:`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
|
||||
: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
|
||||
you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt>
|
||||
is another popular alternative.
|
||||
|
||||
.. _describe_changes:
|
||||
|
||||
Describe your changes
|
||||
|
|
@ -351,7 +292,12 @@ on the changes you are submitting. It is important for a kernel
|
|||
developer to be able to "quote" your changes, using standard e-mail
|
||||
tools, so that they may comment on specific portions of your code.
|
||||
|
||||
For this reason, all patches should be submitted by e-mail "inline".
|
||||
For this reason, all patches should be submitted by e-mail "inline". The
|
||||
easiest way to do this is with ``git send-email``, which is strongly
|
||||
recommended. An interactive tutorial for ``git send-email`` is available at
|
||||
https://git-send-email.io.
|
||||
|
||||
If you choose not to use ``git send-email``:
|
||||
|
||||
.. warning::
|
||||
|
||||
|
|
@ -371,23 +317,14 @@ See :ref:`Documentation/process/email-clients.rst <email_clients>`
|
|||
for hints about configuring your e-mail client so that it sends your patches
|
||||
untouched.
|
||||
|
||||
E-mail size
|
||||
-----------
|
||||
|
||||
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. But note
|
||||
that if your patch exceeds 300 kB, it almost certainly needs to be broken up
|
||||
anyway.
|
||||
|
||||
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;
|
||||
ignoring reviewers is a good way to get ignored in return. Review comments
|
||||
or questions that do not lead to a code change should almost certainly
|
||||
which the patch can be improved, in the form of a reply to your email. You must
|
||||
respond to those comments; ignoring reviewers is a good way to get ignored in
|
||||
return. You can simply reply to their emails to answer their comments. Review
|
||||
comments or questions that do not lead to a code change should almost certainly
|
||||
bring about a comment or changelog entry so that the next reviewer better
|
||||
understands what is going on.
|
||||
|
||||
|
|
@ -422,6 +359,7 @@ convention to prefix your subject line with [PATCH]. This lets Linus
|
|||
and other kernel developers more easily distinguish patches from other
|
||||
e-mail discussions.
|
||||
|
||||
``git send-email`` will do this for you automatically.
|
||||
|
||||
|
||||
Sign your work - the Developer's Certificate of Origin
|
||||
|
|
@ -469,6 +407,7 @@ then you just add a line saying::
|
|||
Signed-off-by: Random J Developer <random@developer.example.org>
|
||||
|
||||
using your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||
This will be done for you automatically if you use ``git commit -s``.
|
||||
|
||||
Some people also put extra tags at the end. They'll just be ignored for
|
||||
now, but you can do this to mark internal company procedures or just
|
||||
|
|
@ -796,61 +735,6 @@ either below the ``---`` line or at the very bottom of all other
|
|||
content, right before your email signature.
|
||||
|
||||
|
||||
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. If in doubt you can use
|
||||
the pull request as the cover letter for a normal posting of the patch
|
||||
series, giving the maintainer the option of using either.
|
||||
|
||||
A pull request should have [GIT 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
|
||||
|
||||
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue