Lines Matching +full:patch +full:- +full:address
13 works, see Documentation/process/development-process.rst. Also, read
14 Documentation/process/submit-checklist.rst
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 ----------------------------
46 ---------------------
48 Describe your problem. Whether your patch is a one-line bug fix or
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,
77 The maintainer will thank you if you write your patch description in a
81 Solve only one problem per patch. If your description starts to get
82 long, that's a sign that you probably need to split up your patch.
85 When you submit or resubmit a patch or patch series, include the
86 complete patch description and justification for it. Don't just
87 say that this is version N of the patch (series). Don't expect the
88 subsystem maintainer to refer back to earlier patch versions or referenced
89 URLs to find the patch description and put that into the patch.
90 I.e., the patch (series) and its description should be self-contained.
92 probably didn't even receive earlier versions of the patch.
95 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
100 SHA-1 ID of the commit. Please also include the oneline summary of
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
116 can be found on the web, add 'Link:' tags pointing to it. If the patch is a
122 ``Message-ID`` header of the message without the surrounding angle brackets.
133 patch as submitted.
135 In case your patch fixes a bug, use the 'Closes:' tag with a URL referencing
145 If your patch fixes a bug in a specific commit, e.g. you found an issue using
147 the SHA-1 ID, and the one line summary. Do not split the tag across multiple
163 $ git log -1 --pretty=fixes 54a4f0239f2e
169 ---------------------
171 Separate each **logical change** into a separate patch.
179 group those changes into a single patch. Thus a single logical change
180 is contained within a single patch.
182 The point to remember is that each patch should make an easily understood
183 change that can be verified by reviewers. Each patch should be justifiable
186 If one patch depends on another patch in order for a change to be
187 complete, that is OK. Simply note **"this patch depends on patch X"**
188 in your patch description.
191 ensure that the kernel builds and runs properly after each patch in the
193 splitting your patch series at any point; they will not thank you if you
196 If you cannot condense your patch set into a smaller set of patches,
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.
207 the reviewers time and will get your patch rejected, probably
211 another -- in this case you should not modify the moved code at all in
212 the same patch which moves it. This clearly delineates the act of
217 Check your patches with the patch style checker prior to submission
223 - ERROR: things that are very likely to be wrong
224 - WARNING: things requiring careful review
225 - CHECK: things requiring thought
228 patch.
231 Select the recipients for your patch
232 ------------------------------------
235 any patch to code that they maintain; look through the MAINTAINERS file and the
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.
256 If you have a patch that fixes an exploitable security bug, send that patch
258 to allow distributors to get the patch out to users; in such cases,
259 obviously, the patch should not be sent to any public lists. See also
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 -------------------------------------------------------------------
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.
298 Do not attach the patch as a MIME attachment, compressed or not.
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 --------------------------
313 Your patch will almost certainly get comments from reviewers on ways in
314 which the patch can be improved, in the form of a reply to your email. You must
322 for their time. Code review is a tiring and time-consuming process, and
324 politely and address the problems they have pointed out. When sending a next
325 version, add a ``patch changelog`` to the cover letter or to individual patches
328 Notify people that commented on your patch about new versions by adding them to
331 See Documentation/process/email-clients.rst for recommendations on email
337 ----------------------------------------------------
338 Top-posting is strongly discouraged in Linux kernel development
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?
361 Don't get discouraged - or impatient
362 ------------------------------------
365 busy people and may not get to your patch right away.
369 receive comments within a few weeks (typically 2-3); if that does not
372 - possibly longer during busy times like merge windows.
374 It's also ok to resend the patch or the patch series after a couple of
377 [PATCH Vx RESEND] sub/sys: Condensed patch summary
380 patch or patch series - "RESEND" only applies to resubmission of a
381 patch or patch series which have not been modified in any way from the
385 Include PATCH in the subject
386 -----------------------------
388 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
389 convention to prefix your subject line with [PATCH]. This lets Linus
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
405 patch, which certifies that you wrote it or otherwise have the right to
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
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
450 people handling and transporting the patch, but were not involved in its
451 development. SoB chains should reflect the **real** route a patch took
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
460 development of the patch, or that he/she was in the patch's delivery path.
463 patch but wishes to signify and record their approval of it then they can
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
467 maintainer neither contributed to nor forwarded the patch.
469 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
470 has at least reviewed the patch and has indicated acceptance. Hence patch
472 into an Acked-by: (but note that it is usually better to ask for an
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
482 If a person has had the opportunity to comment on a patch, but has not
483 provided such comments, you may optionally add a ``Cc:`` tag to the patch.
485 person it names - but it should indicate that this person was copied on the
486 patch. This tag documents that potentially interested parties
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
491 attributed by the From: tag) when several people work on a single patch. Since
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
495 chronological history of the patch insofar as possible, regardless of whether
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.
502 Example of a patch submitted by the From: author::
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
532 available on the web. The Link: tag can be used instead of Closes: if the patch
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
542 Reviewed-by:, instead, indicates that the patch has been reviewed and found
548 By offering my Reviewed-by: tag, I state that:
550 (a) I have carried out a technical review of this patch to
554 (b) Any problems, concerns, or questions relating to the patch
563 (d) While I have reviewed the patch and believe it to be sound, I
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
575 increase the likelihood of your patch getting into the kernel.
577 Both Tested-by and Reviewed-by tags, once received on mailing list from tester
579 next versions. However if the patch has changed substantially in following
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
591 A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
595 method for indicating a bug fixed by the patch. See :ref:`describe_changes`
600 patch candidates. For more information, please read
601 Documentation/process/stable-kernel-rules.rst.
605 The canonical patch format
606 --------------------------
608 This section describes how the patch itself should be formatted. Note
609 that, if you have your patches stored in a ``git`` repository, proper patch
610 formatting can be had with ``git format-patch``. The tools cannot create
613 The canonical patch subject line is::
615 Subject: [PATCH 001/123] subsystem: summary phrase
617 The canonical patch message body contains the following:
619 - A ``from`` line specifying the patch author, followed by an empty
620 line (only needed if the person sending the patch is not the author).
622 - The body of the explanation, line wrapped at 75 columns, which will
623 be copied to the permanent changelog to describe this patch.
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,
645 describe the patch which that email contains. The ``summary
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
653 developer discussions which refer to the patch. People will want to
655 patch. It will also be the only thing that people may quickly see
658 --oneline``.
660 For these reasons, the ``summary`` must be no more than 70-75
661 characters, and it must describe both what the patch changes, as well
662 as why the patch might be necessary. It is challenging to be both
663 succinct and descriptive, but that is what a well-written summary
667 brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
668 not considered part of the summary phrase, but describe how the patch
670 the multiple versions of the patch have been sent out in response to
674 If there are four patches in a patch series the individual patches may
677 they have reviewed or applied all of the patches in the patch series.
681 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
682 Subject: [PATCH v2 01/27] x86: fix eflags tracking
683 Subject: [PATCH v2] sub/sys: Condensed patch summary
684 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
689 From: Patch Author <author@example.com>
692 patch in the permanent changelog. If the ``from`` line is missing,
694 the patch author in the changelog.
699 this patch. Including symptoms of the failure which the patch addresses
702 patch. The text should be written in such detail so that when read
704 details to grasp the reasoning for **why** the patch was created.
706 If a patch fixes a compile failure, it may not be necessary to include
708 someone searching for the patch can find it. As in the ``summary
711 The ``---`` marker line serves the essential purpose of marking for
712 patch handling tools where the changelog message ends.
714 One good use for the additional comments after the ``---`` marker is
718 ``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that
725 example of such comments might be ``patch changelogs`` which describe
726 what has changed between the v1 and v2 version of the patch.
728 Please put this information **after** the ``---`` line which separates
729 the changelog from the rest of the patch. The version information is
734 patch::
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+++--
746 See more details on the proper patch format in the following
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
781 series. This way multiple versions of the patch don't become an
784 the cover email text) to link to an earlier version of the patch series.
788 -------------------------------
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
837 letter or in the first patch of the series and it should be placed
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 ----------
856 Andrew Morton, "The perfect patch" (tpp).
859 Jeff Garzik, "Linux kernel patch submission format".
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
877 Linus Torvalds's mail on the canonical patch format:
883 http://halobates.de/on-submitting-patches.pdf