^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _submittingpatches:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) Submitting patches: the essential guide to getting your code into the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ============================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) For a person or company who wishes to submit a change to the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) kernel, the process can sometimes be daunting if you're not familiar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) with "the system." This text is a collection of suggestions which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) can greatly increase the chances of your change being accepted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This document contains a large number of suggestions in a relatively terse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) format. For detailed information on how the kernel development process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) works, see :doc:`development-process`. Also, read :doc:`submit-checklist`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) for a list of items to check before submitting code. If you are submitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) a driver, also read :doc:`submitting-drivers`; for device tree binding patches,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) read :doc:`submitting-patches`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) This documentation assumes that you're using ``git`` to prepare your patches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) If you're unfamiliar with ``git``, you would be well-advised to learn how to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) use it, it will make your life as a kernel developer and in general much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) easier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Obtain a current source tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) If you do not have a repository with the current kernel source handy, use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) ``git`` to obtain one. You'll want to start with the mainline repository,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) which can be grabbed with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Note, however, that you may not want to develop against the mainline tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) directly. Most subsystem maintainers run their own trees and want to see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) patches prepared against those trees. See the **T:** entry for the subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) in the MAINTAINERS file to find that tree, or simply ask the maintainer if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) the tree is not listed there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) .. _describe_changes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Describe your changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Describe your problem. Whether your patch is a one-line bug fix or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) 5000 lines of a new feature, there must be an underlying problem that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) motivated you to do this work. Convince the reviewer that there is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) problem worth fixing and that it makes sense for them to read past the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) first paragraph.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Describe user-visible impact. Straight up crashes and lockups are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) pretty convincing, but not all bugs are that blatant. Even if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) problem was spotted during code review, describe the impact you think
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) it can have on users. Keep in mind that the majority of Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) installations run kernels from secondary stable trees or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) vendor/product-specific trees that cherry-pick only specific patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) from upstream, so include anything that could help route your change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) downstream: provoking circumstances, excerpts from dmesg, crash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) descriptions, performance regressions, latency spikes, lockups, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Quantify optimizations and trade-offs. If you claim improvements in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) performance, memory consumption, stack footprint, or binary size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) include numbers that back them up. But also describe non-obvious
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) costs. Optimizations usually aren't free but trade-offs between CPU,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) memory, and readability; or, when it comes to heuristics, between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) different workloads. Describe the expected downsides of your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) optimization so that the reviewer can weigh costs against benefits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) Once the problem is established, describe what you are actually doing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) about it in technical detail. It's important to describe the change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) in plain English for the reviewer to verify that the code is behaving
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) as you intend it to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) The maintainer will thank you if you write your patch description in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) form which can be easily pulled into Linux's source code management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Solve only one problem per patch. If your description starts to get
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) long, that's a sign that you probably need to split up your patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) See :ref:`split_changes`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) When you submit or resubmit a patch or patch series, include the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) complete patch description and justification for it. Don't just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) say that this is version N of the patch (series). Don't expect the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) subsystem maintainer to refer back to earlier patch versions or referenced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) URLs to find the patch description and put that into the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) I.e., the patch (series) and its description should be self-contained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) This benefits both the maintainers and reviewers. Some reviewers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) probably didn't even receive earlier versions of the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) to do frotz", as if you are giving orders to the codebase to change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) its behaviour.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) If the patch fixes a logged bug entry, refer to that bug entry by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) number and URL. If the patch follows from a mailing list discussion,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) give a URL to the mailing list archive; use the https://lkml.kernel.org/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) redirector with a ``Message-Id``, to ensure that the links cannot become
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) stale.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) However, try to make your explanation understandable without external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) resources. In addition to giving a URL to a mailing list archive or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) bug, summarize the relevant points of the discussion that led to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) patch as submitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) If you want to refer to a specific commit, don't just refer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) SHA-1 ID of the commit. Please also include the oneline summary of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) the commit, to make it easier for reviewers to know what it is about.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Commit e21d2170f36602ae2708 ("video: remove unnecessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) platform_set_drvdata()") removed the unnecessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) platform_set_drvdata(), but left the variable "dev" unused,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) delete it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) You should also be sure to use at least the first twelve characters of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) SHA-1 ID. The kernel repository holds a *lot* of objects, making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) collisions with shorter IDs a real possibility. Bear in mind that, even if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) there is no collision with your six-character ID now, that condition may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) change five years from now.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) If your patch fixes a bug in a specific commit, e.g. you found an issue using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) the SHA-1 ID, and the one line summary. Do not split the tag across multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) parsing scripts. For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) The following ``git config`` settings can be used to add a pretty format for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) outputting the above style in the ``git log`` or ``git show`` commands::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) [core]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) abbrev = 12
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) [pretty]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) fixes = Fixes: %h (\"%s\")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) An example call::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) $ git log -1 --pretty=fixes 54a4f0239f2e
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) .. _split_changes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Separate your changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Separate each **logical change** into a separate patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) For example, if your changes include both bug fixes and performance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) enhancements for a single driver, separate those changes into two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) or more patches. If your changes include an API update, and a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) driver which uses that new API, separate those into two patches.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) On the other hand, if you make a single change to numerous files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) group those changes into a single patch. Thus a single logical change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) is contained within a single patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) The point to remember is that each patch should make an easily understood
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) change that can be verified by reviewers. Each patch should be justifiable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) on its own merits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) If one patch depends on another patch in order for a change to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) complete, that is OK. Simply note **"this patch depends on patch X"**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) in your patch description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) When dividing your change into a series of patches, take special care to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) ensure that the kernel builds and runs properly after each patch in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) series. Developers using ``git bisect`` to track down a problem can end up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) splitting your patch series at any point; they will not thank you if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) introduce bugs in the middle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) If you cannot condense your patch set into a smaller set of patches,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) then only post say 15 or so at a time and wait for review and integration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) Style-check your changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Check your patch for basic style violations, details of which can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) :ref:`Documentation/process/coding-style.rst <codingstyle>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Failure to do so simply wastes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) the reviewers time and will get your patch rejected, probably
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) without even being read.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) One significant exception is when moving code from one file to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) another -- in this case you should not modify the moved code at all in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) the same patch which moves it. This clearly delineates the act of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) moving the code and your changes. This greatly aids review of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) actual differences and allows tools to better track the history of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) the code itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) Check your patches with the patch style checker prior to submission
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) (scripts/checkpatch.pl). Note, though, that the style checker should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) viewed as a guide, not as a replacement for human judgment. If your code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) looks better with a violation then its probably best left alone.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) The checker reports at three levels:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) - ERROR: things that are very likely to be wrong
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) - WARNING: things requiring careful review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) - CHECK: things requiring thought
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) You should be able to justify all violations that remain in your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Select the recipients for your patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) You should always copy the appropriate subsystem maintainer(s) on any patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) to code that they maintain; look through the MAINTAINERS file and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) source code revision history to see who those maintainers are. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) script scripts/get_maintainer.pl can be very useful at this step. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) cannot find a maintainer for the subsystem you are working on, Andrew
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) You should also normally choose at least one mailing list to receive a copy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) of your patch set. linux-kernel@vger.kernel.org functions as a list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) last resort, but the volume on that list has caused a number of developers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) to tune it out. Look in the MAINTAINERS file for a subsystem-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) list; your patch will probably get more attention there. Please do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) spam unrelated lists, though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Many kernel-related lists are hosted on vger.kernel.org; you can find a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) list of them at http://vger.kernel.org/vger-lists.html. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) kernel-related lists hosted elsewhere as well, though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) Do not send more than 15 patches at once to the vger mailing lists!!!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Linus Torvalds is the final arbiter of all changes accepted into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) He gets a lot of e-mail, and, at this point, very few patches go through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Linus directly, so typically you should do your best to -avoid-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) sending him e-mail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) If you have a patch that fixes an exploitable security bug, send that patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) to security@kernel.org. For severe bugs, a short embargo may be considered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) to allow distributors to get the patch out to users; in such cases,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) obviously, the patch should not be sent to any public lists. See also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) :doc:`/admin-guide/security-bugs`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Patches that fix a severe bug in a released kernel should be directed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) toward the stable maintainers by putting a line like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) Cc: stable@vger.kernel.org
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) into the sign-off area of your patch (note, NOT an email recipient). You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) should also read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) in addition to this file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) If changes affect userland-kernel interfaces, please send the MAN-PAGES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) least a notification of the change, so that some information makes its way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) into the manual pages. User-space API changes should also be copied to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) linux-api@vger.kernel.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) For small patches you may want to CC the Trivial Patch Monkey
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) trivial@kernel.org which collects "trivial" patches. Have a look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) into the MAINTAINERS file for its current manager.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) Trivial patches must qualify for one of the following rules:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) - Spelling fixes in documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) - Spelling fixes for errors which could break :manpage:`grep(1)`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) - Warning fixes (cluttering with useless warnings is bad)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) - Compilation fixes (only if they are actually correct)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) - Runtime fixes (only if they actually fix things)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) - Removing use of deprecated functions/macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) - Contact detail and documentation fixes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) - Non-portable code replaced by portable code (even in arch-specific,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) since people copy, as long as it's trivial)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) - Any fix by the author/maintainer of the file (ie. patch monkey
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) in re-transmission mode)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) No MIME, no links, no compression, no attachments. Just plain text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) -------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Linus and other kernel developers need to be able to read and comment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) on the changes you are submitting. It is important for a kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) developer to be able to "quote" your changes, using standard e-mail
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) tools, so that they may comment on specific portions of your code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) For this reason, all patches should be submitted by e-mail "inline". The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) easiest way to do this is with ``git send-email``, which is strongly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) recommended. An interactive tutorial for ``git send-email`` is available at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) https://git-send-email.io.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) If you choose not to use ``git send-email``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) Be wary of your editor's word-wrap corrupting your patch,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) if you choose to cut-n-paste your patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Do not attach the patch as a MIME attachment, compressed or not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) Many popular e-mail applications will not always transmit a MIME
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) attachment as plain text, making it impossible to comment on your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) code. A MIME attachment also takes Linus a bit more time to process,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) decreasing the likelihood of your MIME-attached change being accepted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) Exception: If your mailer is mangling patches then someone may ask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) you to re-send them using MIME.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) See :doc:`/process/email-clients` for hints about configuring your e-mail
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) client so that it sends your patches untouched.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) Respond to review comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) Your patch will almost certainly get comments from reviewers on ways in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) which the patch can be improved, in the form of a reply to your email. You must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) respond to those comments; ignoring reviewers is a good way to get ignored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) return. You can simply reply to their emails to answer their comments. Review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) comments or questions that do not lead to a code change should almost certainly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) bring about a comment or changelog entry so that the next reviewer better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) understands what is going on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) Be sure to tell the reviewers what changes you are making and to thank them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) for their time. Code review is a tiring and time-consuming process, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) reviewers sometimes get grumpy. Even in that case, though, respond
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) politely and address the problems they have pointed out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) See :doc:`email-clients` for recommendations on email
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) clients and mailing list etiquette.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) Don't get discouraged - or impatient
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) After you have submitted your change, be patient and wait. Reviewers are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) busy people and may not get to your patch right away.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) Once upon a time, patches used to disappear into the void without comment,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) but the development process works more smoothly than that now. You should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) receive comments within a week or so; if that does not happen, make sure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) that you have sent your patches to the right place. Wait for a minimum of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) one week before resubmitting or pinging reviewers - possibly longer during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) busy times like merge windows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) Include PATCH in the subject
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) Due to high e-mail traffic to Linus, and to linux-kernel, it is common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) convention to prefix your subject line with [PATCH]. This lets Linus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) and other kernel developers more easily distinguish patches from other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) e-mail discussions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) ``git send-email`` will do this for you automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) Sign your work - the Developer's Certificate of Origin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) ------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) To improve tracking of who did what, especially with patches that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) percolate to their final resting place in the kernel through several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) layers of maintainers, we've introduced a "sign-off" procedure on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) patches that are being emailed around.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) The sign-off is a simple line at the end of the explanation for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) patch, which certifies that you wrote it or otherwise have the right to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) pass it on as an open-source patch. The rules are pretty simple: if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) can certify the below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) Developer's Certificate of Origin 1.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) By making a contribution to this project, I certify that:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) (a) The contribution was created in whole or in part by me and I
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) have the right to submit it under the open source license
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) indicated in the file; or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) (b) The contribution is based upon previous work that, to the best
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) of my knowledge, is covered under an appropriate open source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) license and I have the right under that license to submit that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) work with modifications, whether created in whole or in part
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) by me, under the same open source license (unless I am
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) permitted to submit under a different license), as indicated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) in the file; or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) (c) The contribution was provided directly to me by some other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) person who certified (a), (b) or (c) and I have not modified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) (d) I understand and agree that this project and the contribution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) are public and that a record of the contribution (including all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) personal information I submit with it, including my sign-off) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) maintained indefinitely and may be redistributed consistent with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) this project or the open source license(s) involved.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) then you just add a line saying::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) Signed-off-by: Random J Developer <random@developer.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) using your real name (sorry, no pseudonyms or anonymous contributions.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) This will be done for you automatically if you use ``git commit -s``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) Some people also put extra tags at the end. They'll just be ignored for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) now, but you can do this to mark internal company procedures or just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) point out some special detail about the sign-off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) When to use Acked-by:, Cc:, and Co-developed-by:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) ------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) The Signed-off-by: tag indicates that the signer was involved in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) development of the patch, or that he/she was in the patch's delivery path.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) If a person was not directly involved in the preparation or handling of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) patch but wishes to signify and record their approval of it then they can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) ask to have an Acked-by: line added to the patch's changelog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) Acked-by: is often used by the maintainer of the affected code when that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) maintainer neither contributed to nor forwarded the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) has at least reviewed the patch and has indicated acceptance. Hence patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) mergers will sometimes manually convert an acker's "yep, looks good to me"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) into an Acked-by: (but note that it is usually better to ask for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) explicit ack).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) Acked-by: does not necessarily indicate acknowledgement of the entire patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) For example, if a patch affects multiple subsystems and has an Acked-by: from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) one subsystem maintainer then this usually indicates acknowledgement of just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) the part which affects that maintainer's code. Judgement should be used here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) When in doubt people should refer to the original discussion in the mailing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) list archives.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) If a person has had the opportunity to comment on a patch, but has not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) provided such comments, you may optionally add a ``Cc:`` tag to the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) This is the only tag which might be added without an explicit action by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) person it names - but it should indicate that this person was copied on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) patch. This tag documents that potentially interested parties
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) have been included in the discussion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) Co-developed-by: states that the patch was co-created by multiple developers;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) it is a used to give attribution to co-authors (in addition to the author
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) attributed by the From: tag) when several people work on a single patch. Since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) followed by a Signed-off-by: of the associated co-author. Standard sign-off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) chronological history of the patch insofar as possible, regardless of whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) the author is attributed via From: or Co-developed-by:. Notably, the last
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) Signed-off-by: must always be that of the developer submitting the patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) Note, the From: tag is optional when the From: author is also the person (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) email) listed in the From: line of the email header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) Example of a patch submitted by the From: author::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) <changelog>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) Co-developed-by: First Co-Author <first@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) Signed-off-by: First Co-Author <first@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) Co-developed-by: Second Co-Author <second@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) Signed-off-by: Second Co-Author <second@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Signed-off-by: From Author <from@author.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) Example of a patch submitted by a Co-developed-by: author::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) From: From Author <from@author.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) <changelog>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) Co-developed-by: Random Co-Author <random@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) Signed-off-by: Random Co-Author <random@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) Signed-off-by: From Author <from@author.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) ----------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) The Reported-by tag gives credit to people who find bugs and report them and it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) hopefully inspires them to help us again in the future. Please note that if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) the bug was reported in private, then ask for permission first before using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) Reported-by tag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) A Tested-by: tag indicates that the patch has been successfully tested (in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) some environment) by the person named. This tag informs maintainers that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) some testing has been performed, provides a means to locate testers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) future patches, and ensures credit for the testers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) Reviewed-by:, instead, indicates that the patch has been reviewed and found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) acceptable according to the Reviewer's Statement:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) Reviewer's statement of oversight
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) By offering my Reviewed-by: tag, I state that:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) (a) I have carried out a technical review of this patch to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) evaluate its appropriateness and readiness for inclusion into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) the mainline kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) (b) Any problems, concerns, or questions relating to the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) have been communicated back to the submitter. I am satisfied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) with the submitter's response to my comments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) (c) While there may be things that could be improved with this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) submission, I believe that it is, at this time, (1) a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) worthwhile modification to the kernel, and (2) free of known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) issues which would argue against its inclusion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) (d) While I have reviewed the patch and believe it to be sound, I
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) do not (unless explicitly stated elsewhere) make any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) warranties or guarantees that it will achieve its stated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) purpose or function properly in any given situation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) A Reviewed-by tag is a statement of opinion that the patch is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) appropriate modification of the kernel without any remaining serious
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) technical issues. Any interested reviewer (who has done the work) can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) offer a Reviewed-by tag for a patch. This tag serves to give credit to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) reviewers and to inform maintainers of the degree of review which has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) done on the patch. Reviewed-by: tags, when supplied by reviewers known to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) understand the subject area and to perform thorough reviews, will normally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) increase the likelihood of your patch getting into the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) Both Tested-by and Reviewed-by tags, once received on mailing list from tester
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) or reviewer, should be added by author to the applicable patches when sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) next versions. However if the patch has changed substantially in following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) version, these tags might not be applicable anymore and thus should be removed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) in the patch changelog (after the '---' separator).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) A Suggested-by: tag indicates that the patch idea is suggested by the person
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) named and ensures credit to the person for the idea. Please note that this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) tag should not be added without the reporter's permission, especially if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) idea was not posted in a public forum. That said, if we diligently credit our
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) idea reporters, they will, hopefully, be inspired to help us again in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) future.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) is used to make it easy to determine where a bug originated, which can help
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) review a bug fix. This tag also assists the stable kernel team in determining
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) which stable kernel versions should receive your fix. This is the preferred
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) method for indicating a bug fixed by the patch. See :ref:`describe_changes`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) .. _the_canonical_patch_format:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) The canonical patch format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) This section describes how the patch itself should be formatted. Note
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) that, if you have your patches stored in a ``git`` repository, proper patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) formatting can be had with ``git format-patch``. The tools cannot create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) the necessary text, though, so read the instructions below anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) The canonical patch subject line is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) Subject: [PATCH 001/123] subsystem: summary phrase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) The canonical patch message body contains the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) - A ``from`` line specifying the patch author, followed by an empty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) line (only needed if the person sending the patch is not the author).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) - The body of the explanation, line wrapped at 75 columns, which will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) be copied to the permanent changelog to describe this patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) - An empty line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) - The ``Signed-off-by:`` lines, described above, which will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) also go in the changelog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) - A marker line containing simply ``---``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) - Any additional comments not suitable for the changelog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) - The actual patch (``diff`` output).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) The Subject line format makes it very easy to sort the emails
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) alphabetically by subject line - pretty much any email reader will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) support that - since because the sequence number is zero-padded,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) the numerical and alphabetic sort is the same.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) The ``subsystem`` in the email's Subject should identify which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) area or subsystem of the kernel is being patched.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) The ``summary phrase`` in the email's Subject should concisely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) describe the patch which that email contains. The ``summary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) phrase`` should not be a filename. Do not use the same ``summary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) phrase`` for every patch in a whole patch series (where a ``patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) series`` is an ordered sequence of multiple, related patches).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) Bear in mind that the ``summary phrase`` of your email becomes a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) globally-unique identifier for that patch. It propagates all the way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) into the ``git`` changelog. The ``summary phrase`` may later be used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) developer discussions which refer to the patch. People will want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) google for the ``summary phrase`` to read discussion regarding that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) patch. It will also be the only thing that people may quickly see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) when, two or three months later, they are going through perhaps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) thousands of patches using tools such as ``gitk`` or ``git log
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) --oneline``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) For these reasons, the ``summary`` must be no more than 70-75
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) characters, and it must describe both what the patch changes, as well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) as why the patch might be necessary. It is challenging to be both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) succinct and descriptive, but that is what a well-written summary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) should do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) The ``summary phrase`` may be prefixed by tags enclosed in square
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) not considered part of the summary phrase, but describe how the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) should be treated. Common tags might include a version descriptor if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) the multiple versions of the patch have been sent out in response to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) comments. If there are four patches in a patch series the individual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) that developers understand the order in which the patches should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) applied and that they have reviewed or applied all of the patches in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) the patch series.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) A couple of example Subjects::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) Subject: [PATCH v2 01/27] x86: fix eflags tracking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) The ``from`` line must be the very first line in the message body,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) and has the form:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) From: Patch Author <author@example.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) The ``from`` line specifies who will be credited as the author of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) patch in the permanent changelog. If the ``from`` line is missing,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) then the ``From:`` line from the email header will be used to determine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) the patch author in the changelog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) The explanation body will be committed to the permanent source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) changelog, so should make sense to a competent reader who has long
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) since forgotten the immediate details of the discussion that might
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) have led to this patch. Including symptoms of the failure which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) patch addresses (kernel log messages, oops messages, etc.) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) especially useful for people who might be searching the commit logs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) looking for the applicable patch. If a patch fixes a compile failure,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) it may not be necessary to include _all_ of the compile failures; just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) enough that it is likely that someone searching for the patch can find
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) it. As in the ``summary phrase``, it is important to be both succinct as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) well as descriptive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) The ``---`` marker line serves the essential purpose of marking for patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) handling tools where the changelog message ends.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) One good use for the additional comments after the ``---`` marker is for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) a ``diffstat``, to show what files have changed, and the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) inserted and deleted lines per file. A ``diffstat`` is especially useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) on bigger patches. Other comments relevant only to the moment or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) maintainer, not suitable for the permanent changelog, should also go
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) here. A good example of such comments might be ``patch changelogs``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) which describe what has changed between the v1 and v2 version of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) If you are going to include a ``diffstat`` after the ``---`` marker, please
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) the top of the kernel source tree and don't use too much horizontal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) space (easily fit in 80 columns, maybe with some indentation). (``git``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) generates appropriate diffstats by default.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) See more details on the proper patch format in the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) references.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) .. _explicit_in_reply_to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) Explicit In-Reply-To headers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) It can be helpful to manually add In-Reply-To: headers to a patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) (e.g., when using ``git send-email``) to associate the patch with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) previous relevant discussion, e.g. to link a bug fix to the email with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) the bug report. However, for a multi-patch series, it is generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) best to avoid using In-Reply-To: to link to older versions of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) series. This way multiple versions of the patch don't become an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) unmanageable forest of references in email clients. If a link is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) the cover email text) to link to an earlier version of the patch series.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) Providing base tree information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) When other developers receive your patches and start the review process,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) it is often useful for them to know where in the tree history they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) should place your work. This is particularly useful for automated CI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) processes that attempt to run a series of tests in order to establish
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) the quality of your submission before the maintainer starts the review.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) If you are using ``git format-patch`` to generate your patches, you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) automatically include the base tree information in your submission by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) using the ``--base`` flag. The easiest and most convenient way to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) this option is with topical branches::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) $ git checkout -t -b my-topical-branch master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) Branch 'my-topical-branch' set up to track local branch 'master'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) Switched to a new branch 'my-topical-branch'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) [perform your edits and commits]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) $ git format-patch --base=auto --cover-letter -o outgoing/ master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) outgoing/0000-cover-letter.patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) outgoing/0001-First-Commit.patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) outgoing/...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) notice that it will have the ``base-commit:`` trailer at the very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) bottom, which provides the reviewer and the CI tools enough information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) to properly perform ``git am`` without worrying about conflicts::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) $ git checkout -b patch-review [base-commit-id]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) Switched to a new branch 'patch-review'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) $ git am patches.mbox
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) Applying: First Commit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) Applying: ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) Please see ``man git-format-patch`` for more information about this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) The ``--base`` feature was introduced in git version 2.9.0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) If you are not using git to format your patches, you can still include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) the same ``base-commit`` trailer to indicate the commit hash of the tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) on which your work is based. You should add it either in the cover
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) letter or in the first patch of the series and it should be placed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) either below the ``---`` line or at the very bottom of all other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) content, right before your email signature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) Andrew Morton, "The perfect patch" (tpp).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) Jeff Garzik, "Linux kernel patch submission format".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) <http://www.kroah.com/log/linux/maintainer.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) <http://www.kroah.com/log/linux/maintainer-02.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) <http://www.kroah.com/log/linux/maintainer-03.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) <http://www.kroah.com/log/linux/maintainer-04.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) <http://www.kroah.com/log/linux/maintainer-05.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) <http://www.kroah.com/log/linux/maintainer-06.html>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) <https://lkml.org/lkml/2005/7/11/336>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) Kernel Documentation/process/coding-style.rst:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) :ref:`Documentation/process/coding-style.rst <codingstyle>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) Linus Torvalds's mail on the canonical patch format:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) <http://lkml.org/lkml/2005/4/7/183>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) Andi Kleen, "On submitting kernel patches"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) Some strategies to get difficult or controversial changes in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) http://halobates.de/on-submitting-patches.pdf
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags