Commit 9f364b60 authored by Drew DeVault's avatar Drew DeVault Committed by Jonathan Corbet

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: default avatarDrew DeVault <sir@cmpwn.com>
Link: https://lore.kernel.org/r/20200903160545.83185-5-sir@cmpwn.comSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 4ebdf7be
...@@ -18,11 +18,10 @@ submitting code. If you are submitting a driver, also read ...@@ -18,11 +18,10 @@ submitting code. If you are submitting a driver, also read
for device tree binding patches, read for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.rst. Documentation/devicetree/bindings/submitting-patches.rst.
Many of these steps describe the default behavior of the ``git`` version This documentation assumes that you're using ``git`` to prepare your patches.
control system; if you use ``git`` to prepare your patches, you'll find much If you're unfamiliar with ``git``, you would be well-advised to learn how to
of the mechanical work done for you, though you'll still need to prepare use it, it will make your life as a kernel developer and in general much
and document a sensible set of patches. In general, use of ``git`` will make easier.
your life as a kernel developer easier.
Obtain a current source tree Obtain a current source tree
---------------------------- ----------------------------
...@@ -39,64 +38,6 @@ patches prepared against those trees. See the **T:** entry for the subsystem ...@@ -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 in the MAINTAINERS file to find that tree, or simply ask the maintainer if
the tree is not listed there. 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_changes:
Describe your changes Describe your changes
...@@ -351,7 +292,12 @@ on the changes you are submitting. It is important for a kernel ...@@ -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 developer to be able to "quote" your changes, using standard e-mail
tools, so that they may comment on specific portions of your code. 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:: .. warning::
...@@ -371,23 +317,14 @@ See :ref:`Documentation/process/email-clients.rst <email_clients>` ...@@ -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 for hints about configuring your e-mail client so that it sends your patches
untouched. 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 Respond to review comments
-------------------------- --------------------------
Your patch will almost certainly get comments from reviewers on ways in Your patch will almost certainly get comments from reviewers on ways in
which the patch can be improved. You must respond to those comments; which the patch can be improved, in the form of a reply to your email. You must
ignoring reviewers is a good way to get ignored in return. Review comments respond to those comments; ignoring reviewers is a good way to get ignored in
or questions that do not lead to a code change should almost certainly 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 bring about a comment or changelog entry so that the next reviewer better
understands what is going on. understands what is going on.
...@@ -422,6 +359,7 @@ convention to prefix your subject line with [PATCH]. This lets Linus ...@@ -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 and other kernel developers more easily distinguish patches from other
e-mail discussions. e-mail discussions.
``git send-email`` will do this for you automatically.
Sign your work - the Developer's Certificate of Origin Sign your work - the Developer's Certificate of Origin
...@@ -469,6 +407,7 @@ then you just add a line saying:: ...@@ -469,6 +407,7 @@ then you just add a line saying::
Signed-off-by: Random J Developer <random@developer.example.org> Signed-off-by: Random J Developer <random@developer.example.org>
using your real name (sorry, no pseudonyms or anonymous contributions.) 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 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 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 ...@@ -796,61 +735,6 @@ either below the ``---`` line or at the very bottom of all other
content, right before your email signature. 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 References
---------- ----------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment