Improvements to submitting-patches.rst
Subsystems (2)
v3 cover Improvements to submitting-patches.rst
Thanks for the feedback Jonathan! This one should be good to go.
- Fixes the allocation of header numbering removal between the patches
- Corrects the length of the --- under each header
- Adds DCO context to the new maintainer document
- Removes information about git request-pull
Drew DeVault (4):
submitting-patches.rst: remove heading numbering Documentation/process: expand plain-text advice Documentation/maintainer: rehome sign-off process submitting-patches.rst: presume git will be used
Documentation/maintainer/index.rst | 1 + .../maintainer/modifying-patches.rst | 50 ++++ Documentation/process/email-clients.rst | 5 + Documentation/process/submitting-patches.rst | 257 ++++-------------- 4 files changed, 105 insertions(+), 208 deletions(-) create mode 100644 Documentation/maintainer/modifying-patches.rst
Signature · 1 line
2.28.0
PATCH v3 1/4 submitting-patches.rst: remove heading numbering
This follows similar changes throughout Documentation; these numbers tend to get outdated and are not especially useful.
--- Documentation/process/submitting-patches.rst | 68 ++++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-)
Documentation/process/submitting-patches.rst +34 -34
@@ -24,8 +24,8 @@ 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. -0) Obtain a current source tree -------------------------------- +Obtain a current source tree +---------------------------- 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,
@@ -99,8 +99,8 @@ is another popular alternative. .. _describe_changes: -2) Describe your changes ------------------------- +Describe your changes +--------------------- Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that
@@ -203,8 +203,8 @@ An example call:: .. _split_changes: -3) Separate your changes ------------------------- +Separate your changes +--------------------- Separate each **logical change** into a separate patch.
@@ -236,8 +236,8 @@ then only post say 15 or so at a time and wait for review and integration. -4) Style-check your changes ---------------------------- +Style-check your changes +------------------------ Check your patch for basic style violations, details of which can be found in
@@ -267,8 +267,8 @@ You should be able to justify all violations that remain in your patch. -5) Select the recipients for your patch ---------------------------------------- +Select the recipients for your patch +------------------------------------ You should always copy the appropriate subsystem maintainer(s) on any patch to code that they maintain; look through the MAINTAINERS file and the
@@ -342,8 +342,8 @@ Trivial patches must qualify for one of the following rules: -6) No MIME, no links, no compression, no attachments. Just plain text ----------------------------------------------------------------------- +No MIME, no links, no compression, no attachments. Just plain text +------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel
@@ -370,8 +370,8 @@ See :ref:`Documentation/process/email-clients.rst <email_clients>` for hints about configuring your e-mail client so that it sends your patches untouched. -7) E-mail size --------------- +E-mail size +----------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size,
@@ -380,8 +380,8 @@ 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. -8) Respond to review comments ------------------------------ +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;
@@ -396,8 +396,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. -9) Don't get discouraged - or impatient ---------------------------------------- +Don't get discouraged - or impatient +------------------------------------ After you have submitted your change, be patient and wait. Reviewers are busy people and may not get to your patch right away.
@@ -410,8 +410,8 @@ one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows. -10) Include PATCH in the subject --------------------------------- +Include PATCH in the subject +----------------------------- Due to high e-mail traffic to Linus, and to linux-kernel, it is common convention to prefix your subject line with [PATCH]. This lets Linus
@@ -420,8 +420,8 @@ e-mail discussions. -11) Sign your work - the Developer's Certificate of Origin ----------------------------------------------------------- +Sign your work - the Developer's Certificate of Origin +------------------------------------------------------ To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several
@@ -517,8 +517,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your tree. -12) When to use Acked-by:, Cc:, and Co-developed-by: -------------------------------------------------------- +When to use Acked-by:, Cc:, and Co-developed-by: +------------------------------------------------ The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path.
@@ -586,8 +586,8 @@ Example of a patch submitted by a Co-developed-by: author:: Signed-off-by: Submitting Co-Author <[email protected]> -13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: --------------------------------------------------------------------------- +Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +---------------------------------------------------------------------- The Reported-by tag gives credit to people who find bugs and report them and it hopefully inspires them to help us again in the future. Please note that if
@@ -650,8 +650,8 @@ for more details. .. _the_canonical_patch_format: -14) The canonical patch format ------------------------------- +The canonical patch format +-------------------------- This section describes how the patch itself should be formatted. Note that, if you have your patches stored in a ``git`` repository, proper patch
@@ -773,8 +773,8 @@ references. .. _explicit_in_reply_to: -15) Explicit In-Reply-To headers --------------------------------- +Explicit In-Reply-To headers +---------------------------- It can be helpful to manually add In-Reply-To: headers to a patch (e.g., when using ``git send-email``) to associate the patch with
@@ -787,8 +787,8 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in the cover email text) to link to an earlier version of the patch series. -16) Providing base tree information ------------------------------------ +Providing base tree information +------------------------------- When other developers receive your patches and start the review process, it is often useful for them to know where in the tree history they
@@ -838,8 +838,8 @@ either below the ``---`` line or at the very bottom of all other content, right before your email signature. -17) Sending ``git pull`` requests ---------------------------------- +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
Signature · 1 line
2.28.0
PATCH v3 2/4 Documentation/process: expand plain-text advice
In reply to Drew DeVaultThis adds a link to https://useplaintext.email to email-clients.rst, which is a more exhaustive resource on configuring various mail clients for plain text use. submitting-patches.rst is also updated to direct readers to email-clients.rst to equip new contributors with the requisite knowledge to become a good participant on the mailing lists.
--- Documentation/process/email-clients.rst | 5 +++++ Documentation/process/submitting-patches.rst | 3 +++ 2 files changed, 8 insertions(+)
Documentation/process/email-clients.rst +5 -0
@@ -25,6 +25,11 @@ attachments, but then the attachments should have content-type it makes quoting portions of the patch more difficult in the patch review process. +It's also strongly recommended that you use plain text in your email body, +for patches and other emails alike. https://useplaintext.email may be useful +for information on how to configure your preferred email client, as well as +listing recommended email clients should you not already have a preference. + Email clients that are used for Linux kernel patches should send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines.
Documentation/process/submitting-patches.rst +3 -0
@@ -395,6 +395,9 @@ for their time. Code review is a tiring and time-consuming process, and reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. +See :ref:`Documentation/process/email-clients.rst` for recommendations on email +clients and mailing list etiquette. + Don't get discouraged - or impatient ------------------------------------
Signature · 1 line
2.28.0
PATCH v3 3/4 Documentation/maintainer: rehome sign-off process
In reply to Drew DeVaultThe repeated sign-offs necessary when a subsystem maintainer modifies an incoming patch has been moved from submitting-patches.rst to Documentation/maintainer, since the affairs of a subsystem maintainer are not especially relevant to someone reading a guide for how to submit their first patch.
--- Documentation/maintainer/index.rst | 1 + .../maintainer/modifying-patches.rst | 50 +++++++++++++++++++ Documentation/process/submitting-patches.rst | 46 ----------------- 3 files changed, 51 insertions(+), 46 deletions(-) create mode 100644 Documentation/maintainer/modifying-patches.rst
Documentation/maintainer/index.rst +1 -0
@@ -13,4 +13,5 @@ additions to this manual. rebasing-and-merging pull-requests maintainer-entry-profile + modifying-patches
Documentation/maintainer/modifying-patches.rst new file +50 -0
50 lines not on this page · raw message
Documentation/process/submitting-patches.rst +0 -46
52 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH v3 4/4 submitting-patches.rst: presume git will be used
In reply to Drew DeVaultGit 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.
--- Documentation/process/submitting-patches.rst | 148 ++----------------- 1 file changed, 16 insertions(+), 132 deletions(-)
Documentation/process/submitting-patches.rst +16 -132
@@ -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
@@ -350,7 +291,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::
@@ -370,23 +316,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.
@@ -421,6 +358,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
@@ -468,6 +406,7 @@ then you just add a line saying:: Signed-off-by: Random J Developer <[email protected]> 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
@@ -795,61 +734,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 ----------
Signature · 1 line
2.28.0
Jonathan Corbet
maintainerQuoted 1 line · On Thu, 3 Sep 2020 12:05:41 -0400 Drew DeVault <[email protected]> wrote:
Thanks for the feedback Jonathan! This one should be good to go.
Indeed it is - applied, thanks.
One little thing: it would have been good to keep Randy's Reviewed-by tag for patch 2; I poked it in.
jon
Quoted 1 line · Jonathan Corbet
Indeed it is - applied, thanks.
Cheers!
Quoted 2 lines
One little thing: it would have been good to keep Randy's Reviewed-by tag for patch 2; I poked it in.
Will remember that for next time. Thanks again for the reviews!