Documentation/SubmittingPatches: enrich the Sphinx output
Do a few changes to make the output look better: - use bullets on trivial patches list; - use monotonic font for tools name; - use :manpage:`foo` for man pages; - don't put all references to maintainer*html at the same line. 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
5903019b2a
commit
9b2c76777a
@ -15,10 +15,10 @@ submitting code. If you are submitting a driver, also read
|
||||
Documentation/SubmittingDrivers; for device tree binding patches, read
|
||||
Documentation/devicetree/bindings/submitting-patches.txt.
|
||||
|
||||
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
|
||||
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
|
||||
and document a sensible set of patches. In general, use of ``git`` will make
|
||||
your life as a kernel developer easier.
|
||||
|
||||
Creating and Sending your Change
|
||||
@ -29,7 +29,7 @@ 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,
|
||||
``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
|
||||
@ -48,13 +48,14 @@ in the next section), but that is the hard way to do kernel development.
|
||||
|
||||
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.
|
||||
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).
|
||||
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.
|
||||
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.
|
||||
|
||||
@ -70,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do::
|
||||
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
|
||||
or unmodified kernel source tree, and generate a ``diff`` against your
|
||||
own source tree. For example::
|
||||
|
||||
MYSRC= /devel/linux
|
||||
@ -81,20 +82,20 @@ own source tree. For example::
|
||||
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 diff(1)-generated
|
||||
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 diff(1), to ensure accuracy.
|
||||
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 <http://savannah.nongnu.org/projects/quilt>
|
||||
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:
|
||||
@ -133,7 +134,7 @@ 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 :ref:`explicit_in_reply_to`.
|
||||
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.
|
||||
@ -156,7 +157,7 @@ its behaviour.
|
||||
If the patch fixes a logged bug entry, refer to that bug entry by
|
||||
number and URL. If the patch follows from a mailing list discussion,
|
||||
give a URL to the mailing list archive; use the https://lkml.kernel.org/
|
||||
redirector with a Message-Id, to ensure that the links cannot become
|
||||
redirector with a ``Message-Id``, to ensure that the links cannot become
|
||||
stale.
|
||||
|
||||
However, try to make your explanation understandable without external
|
||||
@ -181,13 +182,13 @@ 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. For example::
|
||||
``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
|
||||
the 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::
|
||||
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::
|
||||
|
||||
[core]
|
||||
abbrev = 12
|
||||
@ -318,17 +319,17 @@ 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)
|
||||
Compilation fixes (only if they are actually correct)
|
||||
Runtime fixes (only if they actually fix things)
|
||||
Removing use of deprecated functions/macros
|
||||
Contact detail and documentation fixes
|
||||
Non-portable code replaced by portable code (even in arch-specific,
|
||||
since people copy, as long as it's trivial)
|
||||
Any fix by the author/maintainer of the file (ie. patch monkey
|
||||
in re-transmission mode)
|
||||
- Spelling fixes in documentation
|
||||
- Spelling fixes for errors which could break :manpage:`grep(1)`
|
||||
- Warning fixes (cluttering with useless warnings is bad)
|
||||
- Compilation fixes (only if they are actually correct)
|
||||
- Runtime fixes (only if they actually fix things)
|
||||
- Removing use of deprecated functions/macros
|
||||
- Contact detail and documentation fixes
|
||||
- Non-portable code replaced by portable code (even in arch-specific,
|
||||
since people copy, as long as it's trivial)
|
||||
- Any fix by the author/maintainer of the file (ie. patch monkey
|
||||
in re-transmission mode)
|
||||
|
||||
|
||||
|
||||
@ -341,8 +342,11 @@ 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".
|
||||
WARNING: Be wary of your editor's word-wrap corrupting your patch,
|
||||
if you choose to cut-n-paste your patch.
|
||||
|
||||
.. warning::
|
||||
|
||||
Be wary of your editor's word-wrap corrupting your patch,
|
||||
if you choose to cut-n-paste your patch.
|
||||
|
||||
Do not attach the patch as a MIME attachment, compressed or not.
|
||||
Many popular e-mail applications will not always transmit a MIME
|
||||
@ -604,7 +608,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -629,7 +633,7 @@ The canonical patch message body contains the following:
|
||||
|
||||
- Any additional comments not suitable for the changelog.
|
||||
|
||||
- The actual patch (diff output).
|
||||
- The actual patch (``diff`` output).
|
||||
|
||||
The Subject line format makes it very easy to sort the emails
|
||||
alphabetically by subject line - pretty much any email reader will
|
||||
@ -647,13 +651,13 @@ series`` is an ordered sequence of multiple, related patches).
|
||||
|
||||
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
|
||||
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
|
||||
--oneline".
|
||||
thousands of patches using tools such as ``gitk`` or ``git log
|
||||
--oneline``.
|
||||
|
||||
For these reasons, the ``summary`` must be no more than 70-75
|
||||
characters, and it must describe both what the patch changes, as well
|
||||
@ -704,18 +708,18 @@ 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
|
||||
a diffstat, to show what files have changed, and the number of
|
||||
inserted and deleted lines per file. A diffstat is especially useful
|
||||
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``
|
||||
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
|
||||
space (easily fit in 80 columns, maybe with some indentation). (``git``
|
||||
generates appropriate diffstats by default.)
|
||||
|
||||
See more details on the proper patch format in the following
|
||||
@ -761,9 +765,9 @@ interest on a single line; it should look something like::
|
||||
|
||||
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.
|
||||
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
|
||||
@ -775,7 +779,7 @@ 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
|
||||
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
|
||||
@ -803,10 +807,15 @@ Jeff Garzik, "Linux kernel patch submission format".
|
||||
|
||||
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
|
||||
<http://www.kroah.com/log/linux/maintainer.html>
|
||||
|
||||
<http://www.kroah.com/log/linux/maintainer-02.html>
|
||||
|
||||
<http://www.kroah.com/log/linux/maintainer-03.html>
|
||||
|
||||
<http://www.kroah.com/log/linux/maintainer-04.html>
|
||||
|
||||
<http://www.kroah.com/log/linux/maintainer-05.html>
|
||||
|
||||
<http://www.kroah.com/log/linux/maintainer-06.html>
|
||||
|
||||
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
|
||||
@ -820,5 +829,6 @@ Linus Torvalds's mail on the canonical patch format:
|
||||
|
||||
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