Lines Matching +full:always +full:- +full:wait +full:- +full:for +full:- +full:ack
6 For a person or company who wishes to submit a change to the Linux
12 format. For detailed information on how the kernel development process
13 works, see Documentation/process/development-process.rst. Also, read
14 Documentation/process/submit-checklist.rst
15 for a list of items to check before submitting code.
16 For device tree binding patches, read
17 Documentation/devicetree/bindings/submitting-patches.rst.
20 If you're unfamiliar with ``git``, you would be well-advised to learn how to
26 :ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`.
29 ----------------------------
39 patches prepared against those trees. See the **T:** entry for the subsystem
46 ---------------------
48 Describe your problem. Whether your patch is a one-line bug fix or
51 problem worth fixing and that it makes sense for them to read past the
54 Describe user-visible impact. Straight up crashes and lockups are
59 vendor/product-specific trees that cherry-pick only specific patches
64 Quantify optimizations and trade-offs. If you claim improvements in
66 include numbers that back them up. But also describe non-obvious
67 costs. Optimizations usually aren't free but trade-offs between CPU,
74 in plain English for the reviewer to verify that the code is behaving
86 complete patch description and justification for it. Don't just
90 I.e., the patch (series) and its description should be self-contained.
100 SHA-1 ID of the commit. Please also include the oneline summary of
101 the commit, to make it easier for reviewers to know what it is about.
110 SHA-1 ID. The kernel repository holds a *lot* of objects, making
112 there is no collision with your six-character ID now, that condition may
122 ``Message-ID`` header of the message without the surrounding angle brackets.
123 For example::
136 the report in the mailing list archives or a public bug tracker. For example::
147 the SHA-1 ID, and the one line summary. Do not split the tag across multiple
149 parsing scripts. For example::
153 The following ``git config`` settings can be used to add a pretty format for
163 $ git log -1 --pretty=fixes 54a4f0239f2e
169 ---------------------
173 For example, if your changes include both bug fixes and performance
174 enhancements for a single driver, separate those changes into two
186 If one patch depends on another patch in order for a change to be
197 then only post say 15 or so at a time and wait for review and integration.
201 Style-check your changes
202 ------------------------
204 Check your patch for basic style violations, details of which can be
205 found in Documentation/process/coding-style.rst.
211 another -- in this case you should not modify the moved code at all in
219 viewed as a guide, not as a replacement for human judgment. If your code
223 - ERROR: things that are very likely to be wrong
224 - WARNING: things requiring careful review
225 - CHECK: things requiring thought
231 Select the recipients for your patch
232 ------------------------------------
234 You should always copy the appropriate subsystem maintainer(s) and list(s) on
239 maintainer for the subsystem you are working on, Andrew Morton
240 (akpm@linux-foundation.org) serves as a maintainer of last resort.
242 linux-kernel@vger.kernel.org should be used by default for all patches, but the
246 Many kernel-related lists are hosted at kernel.org; you can find a list
247 of them at https://subspace.kernel.org. There are kernel-related lists
251 Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
252 He gets a lot of e-mail, and, at this point, very few patches go through
253 Linus directly, so typically you should do your best to -avoid-
254 sending him e-mail.
257 to security@kernel.org. For severe bugs, a short embargo may be considered
260 Documentation/process/security-bugs.rst.
267 into the sign-off area of your patch (note, NOT an email recipient). You
268 should also read Documentation/process/stable-kernel-rules.rst
271 If changes affect userland-kernel interfaces, please send the MAN-PAGES
272 maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
274 into the manual pages. User-space API changes should also be copied to
275 linux-api@vger.kernel.org.
279 -------------------------------------------------------------------
282 on the changes you are submitting. It is important for a kernel
283 developer to be able to "quote" your changes, using standard e-mail
286 For this reason, all patches should be submitted by e-mail "inline". The
287 easiest way to do this is with ``git send-email``, which is strongly
288 recommended. An interactive tutorial for ``git send-email`` is available at
289 https://git-send-email.io.
291 If you choose not to use ``git send-email``:
295 Be wary of your editor's word-wrap corrupting your patch,
296 if you choose to cut-n-paste your patch.
299 Many popular e-mail applications will not always transmit a MIME
302 decreasing the likelihood of your MIME-attached change being accepted.
305 you to re-send them using MIME.
307 See Documentation/process/email-clients.rst for hints about configuring
308 your e-mail client so that it sends your patches untouched.
311 --------------------------
322 for their time. Code review is a tiring and time-consuming process, and
331 See Documentation/process/email-clients.rst for recommendations on email
337 ----------------------------------------------------
338 Top-posting is strongly discouraged in Linux kernel development
340 easier to follow. For more details see:
346 Q: Were do I find info about this thing called top-posting?
348 Q: Why is top-posting such a bad thing?
349 A: Top-posting.
350 Q: What is the most annoying thing in e-mail?
354 space. For more details see: http://daringfireball.net/2007/07/on_top ::
361 Don't get discouraged - or impatient
362 ------------------------------------
364 After you have submitted your change, be patient and wait. Reviewers are
369 receive comments within a few weeks (typically 2-3); if that does not
371 Wait for a minimum of one week before resubmitting or pinging reviewers
372 - possibly longer during busy times like merge windows.
380 patch or patch series - "RESEND" only applies to resubmission of a
386 -----------------------------
388 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
391 e-mail discussions.
393 ``git send-email`` will do this for you automatically.
396 Sign your work - the Developer's Certificate of Origin
397 ------------------------------------------------------
401 layers of maintainers, we've introduced a "sign-off" procedure on
404 The sign-off is a simple line at the end of the explanation for the
406 pass it on as an open-source patch. The rules are pretty simple: if you
432 personal information I submit with it, including my sign-off) is
438 Signed-off-by: Random J Developer <random@developer.example.org>
441 This will be done for you automatically if you use ``git commit -s``.
442 Reverts should also include "Signed-off-by". ``git revert -s`` does that
443 for you.
445 Some people also put extra tags at the end. They'll just be ignored for
447 point out some special detail about the sign-off.
449 Any further SoBs (Signed-off-by:'s) following the author's SoB are from
456 When to use Acked-by:, Cc:, and Co-developed-by:
457 ------------------------------------------------
459 The Signed-off-by: tag indicates that the signer was involved in the
464 ask to have an Acked-by: line added to the patch's changelog.
466 Acked-by: is often used by the maintainer of the affected code when that
469 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
472 into an Acked-by: (but note that it is usually better to ask for an
473 explicit ack).
475 Acked-by: does not necessarily indicate acknowledgement of the entire patch.
476 For example, if a patch affects multiple subsystems and has an Acked-by: from
485 person it names - but it should indicate that this person was copied on the
489 Co-developed-by: states that the patch was co-created by multiple developers;
490 it is used to give attribution to co-authors (in addition to the author
492 Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
493 followed by a Signed-off-by: of the associated co-author. Standard sign-off
494 procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
496 the author is attributed via From: or Co-developed-by:. Notably, the last
497 Signed-off-by: must always be that of the developer submitting the patch.
506 Co-developed-by: First Co-Author <first@coauthor.example.org>
507 Signed-off-by: First Co-Author <first@coauthor.example.org>
508 Co-developed-by: Second Co-Author <second@coauthor.example.org>
509 Signed-off-by: Second Co-Author <second@coauthor.example.org>
510 Signed-off-by: From Author <from@author.example.org>
512 Example of a patch submitted by a Co-developed-by: author::
518 Co-developed-by: Random Co-Author <random@coauthor.example.org>
519 Signed-off-by: Random Co-Author <random@coauthor.example.org>
520 Signed-off-by: From Author <from@author.example.org>
521 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
522 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
525 Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
526 ----------------------------------------------------------------------
528 The Reported-by tag gives credit to people who find bugs and report them and it
529 hopefully inspires them to help us again in the future. The tag is intended for
534 reported in private, then ask for permission first before using the Reported-by
537 A Tested-by: tag indicates that the patch has been successfully tested (in
539 some testing has been performed, provides a means to locate testers for
540 future patches, and ensures credit for the testers.
542 Reviewed-by:, instead, indicates that the patch has been reviewed and found
548 By offering my Reviewed-by: tag, I state that:
551 evaluate its appropriateness and readiness for inclusion into
568 A Reviewed-by tag is a statement of opinion that the patch is an
571 offer a Reviewed-by tag for a patch. This tag serves to give credit to
573 done on the patch. Reviewed-by: tags, when supplied by reviewers known to
577 Both Tested-by and Reviewed-by tags, once received on mailing list from tester
581 Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
582 in the patch changelog (after the '---' separator).
584 A Suggested-by: tag indicates that the patch idea is suggested by the person
585 named and ensures credit to the person for the idea. Please note that this
595 method for indicating a bug fixed by the patch. See :ref:`describe_changes`
596 for more details.
600 patch candidates. For more information, please read
601 Documentation/process/stable-kernel-rules.rst.
606 --------------------------
610 formatting can be had with ``git format-patch``. The tools cannot create
619 - A ``from`` line specifying the patch author, followed by an empty
622 - The body of the explanation, line wrapped at 75 columns, which will
625 - An empty line.
627 - The ``Signed-off-by:`` lines, described above, which will
630 - A marker line containing simply ``---``.
632 - Any additional comments not suitable for the changelog.
634 - The actual patch (``diff`` output).
637 alphabetically by subject line - pretty much any email reader will
638 support that - since because the sequence number is zero-padded,
647 phrase`` for every patch in a whole patch series (where a ``patch
651 globally-unique identifier for that patch. It propagates all the way
654 google for the ``summary phrase`` to read discussion regarding that
658 --oneline``.
660 For these reasons, the ``summary`` must be no more than 70-75
663 succinct and descriptive, but that is what a well-written summary
671 comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
700 (kernel log messages, oops messages, etc.) are especially useful for
701 people who might be searching the commit logs looking for the applicable
704 details to grasp the reasoning for **why** the patch was created.
708 someone searching for the patch can find it. As in the ``summary
711 The ``---`` marker line serves the essential purpose of marking for
714 One good use for the additional comments after the ``---`` marker is
715 for a ``diffstat``, to show what files have changed, and the number of
718 ``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that
724 suitable for the permanent changelog, should also go here. A good
728 Please put this information **after** the ``---`` line which separates
731 additional information for the reviewers. If it's placed above the
738 Signed-off-by: Author <author@mail>
739 ---
740 V2 -> V3: Removed redundant helper function
741 V1 -> V2: Cleaned up coding style and addressed review comments
743 path/to/file | 5+++--
755 not all backtraces are helpful. For example, early boot call chains are
762 issue. Here is an example of a well-trimmed backtrace::
773 Explicit In-Reply-To headers
774 ----------------------------
776 It can be helpful to manually add In-Reply-To: headers to a patch
777 (e.g., when using ``git send-email``) to associate the patch with
779 the bug report. However, for a multi-patch series, it is generally
780 best to avoid using In-Reply-To: to link to older versions of the
788 -------------------------------
791 it is absolutely necessary for them to know what is the base
796 This is even more important for automated CI processes that attempt to
800 If you are using ``git format-patch`` to generate your patches, you can
802 using the ``--base`` flag. The easiest and most convenient way to use
805 $ git checkout -t -b my-topical-branch master
806 Branch 'my-topical-branch' set up to track local branch 'master'.
807 Switched to a new branch 'my-topical-branch'
811 $ git format-patch --base=auto --cover-letter -o outgoing/ master
812 outgoing/0000-cover-letter.patch
813 outgoing/0001-First-Commit.patch
816 When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
817 notice that it will have the ``base-commit:`` trailer at the very
821 $ git checkout -b patch-review [base-commit-id]
822 Switched to a new branch 'patch-review'
827 Please see ``man git-format-patch`` for more information about this
832 The ``--base`` feature was introduced in git version 2.9.0.
835 the same ``base-commit`` trailer to indicate the commit hash of the tree
838 either below the ``---`` line or at the very bottom of all other
842 and not in some internal, accessible only to you tree - otherwise it
846 -------
854 ----------
860 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
862 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
865 <http://www.kroah.com/log/linux/maintainer-02.html>
867 <http://www.kroah.com/log/linux/maintainer-03.html>
869 <http://www.kroah.com/log/linux/maintainer-04.html>
871 <http://www.kroah.com/log/linux/maintainer-05.html>
873 <http://www.kroah.com/log/linux/maintainer-06.html>
875 Kernel Documentation/process/coding-style.rst
883 http://halobates.de/on-submitting-patches.pdf