Lines Matching +full:check +full:- +full:patch
13 works, see :doc:`development-process`. Also, read :doc:`submit-checklist`
14 for a list of items to check before submitting code. If you are submitting
15 a driver, also read :doc:`submitting-drivers`; for device tree binding patches,
16 read :doc:`submitting-patches`.
19 If you're unfamiliar with ``git``, you would be well-advised to learn how to
24 ----------------------------
41 ---------------------
43 Describe your problem. Whether your patch is a one-line bug fix or
49 Describe user-visible impact. Straight up crashes and lockups are
54 vendor/product-specific trees that cherry-pick only specific patches
59 Quantify optimizations and trade-offs. If you claim improvements in
61 include numbers that back them up. But also describe non-obvious
62 costs. Optimizations usually aren't free but trade-offs between CPU,
72 The maintainer will thank you if you write your patch description in a
76 Solve only one problem per patch. If your description starts to get
77 long, that's a sign that you probably need to split up your patch.
80 When you submit or resubmit a patch or patch series, include the
81 complete patch description and justification for it. Don't just
82 say that this is version N of the patch (series). Don't expect the
83 subsystem maintainer to refer back to earlier patch versions or referenced
84 URLs to find the patch description and put that into the patch.
85 I.e., the patch (series) and its description should be self-contained.
87 probably didn't even receive earlier versions of the patch.
90 instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
94 If the patch fixes a logged bug entry, refer to that bug entry by
95 number and URL. If the patch follows from a mailing list discussion,
97 redirector with a ``Message-Id``, to ensure that the links cannot become
103 patch as submitted.
106 SHA-1 ID of the commit. Please also include the oneline summary of
116 SHA-1 ID. The kernel repository holds a *lot* of objects, making
118 there is no collision with your six-character ID now, that condition may
121 If your patch fixes a bug in a specific commit, e.g. you found an issue using
123 the SHA-1 ID, and the one line summary. Do not split the tag across multiple
139 $ git log -1 --pretty=fixes 54a4f0239f2e
145 ---------------------
147 Separate each **logical change** into a separate patch.
155 group those changes into a single patch. Thus a single logical change
156 is contained within a single patch.
158 The point to remember is that each patch should make an easily understood
159 change that can be verified by reviewers. Each patch should be justifiable
162 If one patch depends on another patch in order for a change to be
163 complete, that is OK. Simply note **"this patch depends on patch X"**
164 in your patch description.
167 ensure that the kernel builds and runs properly after each patch in the
169 splitting your patch series at any point; they will not thank you if you
172 If you cannot condense your patch set into a smaller set of patches,
177 Style-check your changes
178 ------------------------
180 Check your patch for basic style violations, details of which can be
182 :ref:`Documentation/process/coding-style.rst <codingstyle>`.
184 the reviewers time and will get your patch rejected, probably
188 another -- in this case you should not modify the moved code at all in
189 the same patch which moves it. This clearly delineates the act of
194 Check your patches with the patch style checker prior to submission
200 - ERROR: things that are very likely to be wrong
201 - WARNING: things requiring careful review
202 - CHECK: things requiring thought
205 patch.
208 Select the recipients for your patch
209 ------------------------------------
211 You should always copy the appropriate subsystem maintainer(s) on any patch
216 Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
219 of your patch set. linux-kernel@vger.kernel.org functions as a list of
221 to tune it out. Look in the MAINTAINERS file for a subsystem-specific
222 list; your patch will probably get more attention there. Please do not
225 Many kernel-related lists are hosted on vger.kernel.org; you can find a
226 list of them at http://vger.kernel.org/vger-lists.html. There are
227 kernel-related lists hosted elsewhere as well, though.
232 Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
233 He gets a lot of e-mail, and, at this point, very few patches go through
234 Linus directly, so typically you should do your best to -avoid-
235 sending him e-mail.
237 If you have a patch that fixes an exploitable security bug, send that patch
239 to allow distributors to get the patch out to users; in such cases,
240 obviously, the patch should not be sent to any public lists. See also
241 :doc:`/admin-guide/security-bugs`.
248 into the sign-off area of your patch (note, NOT an email recipient). You
250 :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
253 If changes affect userland-kernel interfaces, please send the MAN-PAGES
254 maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
256 into the manual pages. User-space API changes should also be copied to
257 linux-api@vger.kernel.org.
259 For small patches you may want to CC the Trivial Patch Monkey
265 - Spelling fixes in documentation
266 - Spelling fixes for errors which could break :manpage:`grep(1)`
267 - Warning fixes (cluttering with useless warnings is bad)
268 - Compilation fixes (only if they are actually correct)
269 - Runtime fixes (only if they actually fix things)
270 - Removing use of deprecated functions/macros
271 - Contact detail and documentation fixes
272 - Non-portable code replaced by portable code (even in arch-specific,
274 - Any fix by the author/maintainer of the file (ie. patch monkey
275 in re-transmission mode)
280 -------------------------------------------------------------------
284 developer to be able to "quote" your changes, using standard e-mail
287 For this reason, all patches should be submitted by e-mail "inline". The
288 easiest way to do this is with ``git send-email``, which is strongly
289 recommended. An interactive tutorial for ``git send-email`` is available at
290 https://git-send-email.io.
292 If you choose not to use ``git send-email``:
296 Be wary of your editor's word-wrap corrupting your patch,
297 if you choose to cut-n-paste your patch.
299 Do not attach the patch as a MIME attachment, compressed or not.
300 Many popular e-mail applications will not always transmit a MIME
303 decreasing the likelihood of your MIME-attached change being accepted.
306 you to re-send them using MIME.
308 See :doc:`/process/email-clients` for hints about configuring your e-mail
312 --------------------------
314 Your patch will almost certainly get comments from reviewers on ways in
315 which the patch can be improved, in the form of a reply to your email. You must
323 for their time. Code review is a tiring and time-consuming process, and
327 See :doc:`email-clients` for recommendations on email
331 Don't get discouraged - or impatient
332 ------------------------------------
335 busy people and may not get to your patch right away.
341 one week before resubmitting or pinging reviewers - possibly longer during
345 Include PATCH in the subject
346 -----------------------------
348 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
349 convention to prefix your subject line with [PATCH]. This lets Linus
351 e-mail discussions.
353 ``git send-email`` will do this for you automatically.
356 Sign your work - the Developer's Certificate of Origin
357 ------------------------------------------------------
361 layers of maintainers, we've introduced a "sign-off" procedure on
364 The sign-off is a simple line at the end of the explanation for the
365 patch, which certifies that you wrote it or otherwise have the right to
366 pass it on as an open-source patch. The rules are pretty simple: if you
392 personal information I submit with it, including my sign-off) is
398 Signed-off-by: Random J Developer <random@developer.example.org>
401 This will be done for you automatically if you use ``git commit -s``.
405 point out some special detail about the sign-off.
408 When to use Acked-by:, Cc:, and Co-developed-by:
409 ------------------------------------------------
411 The Signed-off-by: tag indicates that the signer was involved in the
412 development of the patch, or that he/she was in the patch's delivery path.
415 patch but wishes to signify and record their approval of it then they can
416 ask to have an Acked-by: line added to the patch's changelog.
418 Acked-by: is often used by the maintainer of the affected code when that
419 maintainer neither contributed to nor forwarded the patch.
421 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
422 has at least reviewed the patch and has indicated acceptance. Hence patch
424 into an Acked-by: (but note that it is usually better to ask for an
427 Acked-by: does not necessarily indicate acknowledgement of the entire patch.
428 For example, if a patch affects multiple subsystems and has an Acked-by: from
434 If a person has had the opportunity to comment on a patch, but has not
435 provided such comments, you may optionally add a ``Cc:`` tag to the patch.
437 person it names - but it should indicate that this person was copied on the
438 patch. This tag documents that potentially interested parties
441 Co-developed-by: states that the patch was co-created by multiple developers;
442 it is a used to give attribution to co-authors (in addition to the author
443 attributed by the From: tag) when several people work on a single patch. Since
444 Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
445 followed by a Signed-off-by: of the associated co-author. Standard sign-off
446 procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
447 chronological history of the patch insofar as possible, regardless of whether
448 the author is attributed via From: or Co-developed-by:. Notably, the last
449 Signed-off-by: must always be that of the developer submitting the patch.
454 Example of a patch submitted by the From: author::
458 Co-developed-by: First Co-Author <first@coauthor.example.org>
459 Signed-off-by: First Co-Author <first@coauthor.example.org>
460 Co-developed-by: Second Co-Author <second@coauthor.example.org>
461 Signed-off-by: Second Co-Author <second@coauthor.example.org>
462 Signed-off-by: From Author <from@author.example.org>
464 Example of a patch submitted by a Co-developed-by: author::
470 Co-developed-by: Random Co-Author <random@coauthor.example.org>
471 Signed-off-by: Random Co-Author <random@coauthor.example.org>
472 Signed-off-by: From Author <from@author.example.org>
473 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
474 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
477 Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
478 ----------------------------------------------------------------------
480 The Reported-by tag gives credit to people who find bugs and report them and it
483 Reported-by tag.
485 A Tested-by: tag indicates that the patch has been successfully tested (in
490 Reviewed-by:, instead, indicates that the patch has been reviewed and found
496 By offering my Reviewed-by: tag, I state that:
498 (a) I have carried out a technical review of this patch to
502 (b) Any problems, concerns, or questions relating to the patch
511 (d) While I have reviewed the patch and believe it to be sound, I
516 A Reviewed-by tag is a statement of opinion that the patch is an
519 offer a Reviewed-by tag for a patch. This tag serves to give credit to
521 done on the patch. Reviewed-by: tags, when supplied by reviewers known to
523 increase the likelihood of your patch getting into the kernel.
525 Both Tested-by and Reviewed-by tags, once received on mailing list from tester
527 next versions. However if the patch has changed substantially in following
529 Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
530 in the patch changelog (after the '---' separator).
532 A Suggested-by: tag indicates that the patch idea is suggested by the person
539 A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
543 method for indicating a bug fixed by the patch. See :ref:`describe_changes`
548 The canonical patch format
549 --------------------------
551 This section describes how the patch itself should be formatted. Note
552 that, if you have your patches stored in a ``git`` repository, proper patch
553 formatting can be had with ``git format-patch``. The tools cannot create
556 The canonical patch subject line is::
558 Subject: [PATCH 001/123] subsystem: summary phrase
560 The canonical patch message body contains the following:
562 - A ``from`` line specifying the patch author, followed by an empty
563 line (only needed if the person sending the patch is not the author).
565 - The body of the explanation, line wrapped at 75 columns, which will
566 be copied to the permanent changelog to describe this patch.
568 - An empty line.
570 - The ``Signed-off-by:`` lines, described above, which will
573 - A marker line containing simply ``---``.
575 - Any additional comments not suitable for the changelog.
577 - The actual patch (``diff`` output).
580 alphabetically by subject line - pretty much any email reader will
581 support that - since because the sequence number is zero-padded,
588 describe the patch which that email contains. The ``summary
590 phrase`` for every patch in a whole patch series (where a ``patch
594 globally-unique identifier for that patch. It propagates all the way
596 developer discussions which refer to the patch. People will want to
598 patch. It will also be the only thing that people may quickly see
601 --oneline``.
603 For these reasons, the ``summary`` must be no more than 70-75
604 characters, and it must describe both what the patch changes, as well
605 as why the patch might be necessary. It is challenging to be both
606 succinct and descriptive, but that is what a well-written summary
610 brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
611 not considered part of the summary phrase, but describe how the patch
613 the multiple versions of the patch have been sent out in response to
615 comments. If there are four patches in a patch series the individual
619 the patch series.
623 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
624 Subject: [PATCH v2 01/27] x86: fix eflags tracking
629 From: Patch Author <author@example.com>
632 patch in the permanent changelog. If the ``from`` line is missing,
634 the patch author in the changelog.
639 have led to this patch. Including symptoms of the failure which the
640 patch addresses (kernel log messages, oops messages, etc.) is
642 looking for the applicable patch. If a patch fixes a compile failure,
644 enough that it is likely that someone searching for the patch can find
648 The ``---`` marker line serves the essential purpose of marking for patch
651 One good use for the additional comments after the ``---`` marker is for
656 here. A good example of such comments might be ``patch changelogs``
658 patch.
660 If you are going to include a ``diffstat`` after the ``---`` marker, please
661 use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
666 See more details on the proper patch format in the following
671 Explicit In-Reply-To headers
672 ----------------------------
674 It can be helpful to manually add In-Reply-To: headers to a patch
675 (e.g., when using ``git send-email``) to associate the patch with
677 the bug report. However, for a multi-patch series, it is generally
678 best to avoid using In-Reply-To: to link to older versions of the
679 series. This way multiple versions of the patch don't become an
682 the cover email text) to link to an earlier version of the patch series.
686 -------------------------------
694 If you are using ``git format-patch`` to generate your patches, you can
696 using the ``--base`` flag. The easiest and most convenient way to use
699 $ git checkout -t -b my-topical-branch master
700 Branch 'my-topical-branch' set up to track local branch 'master'.
701 Switched to a new branch 'my-topical-branch'
705 $ git format-patch --base=auto --cover-letter -o outgoing/ master
706 outgoing/0000-cover-letter.patch
707 outgoing/0001-First-Commit.patch
710 When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
711 notice that it will have the ``base-commit:`` trailer at the very
715 $ git checkout -b patch-review [base-commit-id]
716 Switched to a new branch 'patch-review'
721 Please see ``man git-format-patch`` for more information about this
726 The ``--base`` feature was introduced in git version 2.9.0.
729 the same ``base-commit`` trailer to indicate the commit hash of the tree
731 letter or in the first patch of the series and it should be placed
732 either below the ``---`` line or at the very bottom of all other
737 ----------
739 Andrew Morton, "The perfect patch" (tpp).
742 Jeff Garzik, "Linux kernel patch submission format".
743 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
745 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
748 <http://www.kroah.com/log/linux/maintainer-02.html>
750 <http://www.kroah.com/log/linux/maintainer-03.html>
752 <http://www.kroah.com/log/linux/maintainer-04.html>
754 <http://www.kroah.com/log/linux/maintainer-05.html>
756 <http://www.kroah.com/log/linux/maintainer-06.html>
758 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
761 Kernel Documentation/process/coding-style.rst:
762 :ref:`Documentation/process/coding-style.rst <codingstyle>`
764 Linus Torvalds's mail on the canonical patch format:
770 http://halobates.de/on-submitting-patches.pdf