[PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output
From: Mauro Carvalho Chehab
Date: Mon Sep 19 2016 - 07:13:46 EST
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@xxxxxxxxxxxxxxxx>
---
Documentation/SubmittingPatches | 100 ++++++++++++++++++++++------------------
1 file changed, 55 insertions(+), 45 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 04a4284d8ee4..352771b736cd 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -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@xxxxxxxxxxxxxxx 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
--
2.7.4