From 9b2c76777accbd7b70d73ca540d1e318e4f2c206 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:54 -0300 Subject: [PATCH] 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 Signed-off-by: Jonathan Corbet --- 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 +If you're using ``git``, ``git rebase -i`` can help you with this process. If +you're not using ``git``, ``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". + + + + + 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