^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _development_advancedtopics:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) Advanced topics
^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) At this point, hopefully, you have a handle on how the development process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) works. There is still more to learn, however! This section will cover a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) number of topics which can be helpful for developers wanting to become a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) regular part of the Linux kernel development process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Managing patches with git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) The use of distributed version control for the kernel began in early 2002,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) when Linus first started playing with the proprietary BitKeeper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) application. While BitKeeper was controversial, the approach to software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) version management it embodied most certainly was not. Distributed version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) control enabled an immediate acceleration of the kernel development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) project. In current times, there are several free alternatives to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) BitKeeper. For better or for worse, the kernel project has settled on git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) as its tool of choice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Managing patches with git can make life much easier for the developer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) especially as the volume of those patches grows. Git also has its rough
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) edges and poses certain hazards; it is a young and powerful tool which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) still being civilized by its developers. This document will not attempt to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) teach the reader how to use git; that would be sufficient material for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) long document in its own right. Instead, the focus here will be on how git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) fits into the kernel development process in particular. Developers who
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) wish to come up to speed with git will find more information at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) https://git-scm.com/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) and on various tutorials found on the web.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The first order of business is to read the above sites and get a solid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) understanding of how git works before trying to use it to make patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) available to others. A git-using developer should be able to obtain a copy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) of the mainline repository, explore the revision history, commit changes to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) the tree, use branches, etc. An understanding of git's tools for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) rewriting of history (such as rebase) is also useful. Git comes with its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) own terminology and concepts; a new user of git should know about refs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) remote branches, the index, fast-forward merges, pushes and pulls, detached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) heads, etc. It can all be a little intimidating at the outset, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) concepts are not that hard to grasp with a bit of study.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Using git to generate patches for submission by email can be a good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) exercise while coming up to speed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) When you are ready to start putting up git trees for others to look at, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) will, of course, need a server that can be pulled from. Setting up such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) server with git-daemon is relatively straightforward if you have a system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) which is accessible to the Internet. Otherwise, free, public hosting sites
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) (Github, for example) are starting to appear on the net. Established
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) developers can get an account on kernel.org, but those are not easy to come
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) by; see https://kernel.org/faq/ for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) The normal git workflow involves the use of a lot of branches. Each line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) of development can be separated into a separate "topic branch" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) maintained independently. Branches in git are cheap, there is no reason to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) not make free use of them. And, in any case, you should not do your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) development in any branch which you intend to ask others to pull from.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Publicly-available branches should be created with care; merge in patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) from development branches when they are in complete form and ready to go -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) not before.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) Git provides some powerful tools which can allow you to rewrite your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) development history. An inconvenient patch (one which breaks bisection,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) say, or which has some other sort of obvious bug) can be fixed in place or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) made to disappear from the history entirely. A patch series can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) rewritten as if it had been written on top of today's mainline, even though
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) you have been working on it for months. Changes can be transparently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) shifted from one branch to another. And so on. Judicious use of git's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) ability to revise history can help in the creation of clean patch sets with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) fewer problems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Excessive use of this capability can lead to other problems, though, beyond
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) a simple obsession for the creation of the perfect project history.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Rewriting history will rewrite the changes contained in that history,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) turning a tested (hopefully) kernel tree into an untested one. But, beyond
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) that, developers cannot easily collaborate if they do not have a shared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) view of the project history; if you rewrite history which other developers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) have pulled into their repositories, you will make life much more difficult
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) for those developers. So a simple rule of thumb applies here: history
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) which has been exported to others should generally be seen as immutable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) thereafter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) So, once you push a set of changes to your publicly-available server, those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) changes should not be rewritten. Git will attempt to enforce this rule if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) you try to push changes which do not result in a fast-forward merge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) (i.e. changes which do not share the same history). It is possible to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) override this check, and there may be times when it is necessary to rewrite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) an exported tree. Moving changesets between trees to avoid conflicts in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) linux-next is one example. But such actions should be rare. This is one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) of the reasons why development should be done in private branches (which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) can be rewritten if necessary) and only moved into public branches when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) it's in a reasonably advanced state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) As the mainline (or other tree upon which a set of changes is based)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) advances, it is tempting to merge with that tree to stay on the leading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) edge. For a private branch, rebasing can be an easy way to keep up with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) another tree, but rebasing is not an option once a tree is exported to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) world. Once that happens, a full merge must be done. Merging occasionally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) makes good sense, but overly frequent merges can clutter the history
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) needlessly. Suggested technique in this case is to merge infrequently, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) generally only at specific release points (such as a mainline -rc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) release). If you are nervous about specific changes, you can always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) perform test merges in a private branch. The git "rerere" tool can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) useful in such situations; it remembers how merge conflicts were resolved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) so that you don't have to do the same work twice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) One of the biggest recurring complaints about tools like git is this: the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) mass movement of patches from one repository to another makes it easy to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) slip in ill-advised changes which go into the mainline below the review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) radar. Kernel developers tend to get unhappy when they see that kind of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) thing happening; putting up a git tree with unreviewed or off-topic patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) can affect your ability to get trees pulled in the future. Quoting Linus:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) You can send me patches, but for me to pull a git patch from you, I
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) need to know that you know what you're doing, and I need to be able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) to trust things *without* then having to go and check every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) individual change by hand.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) (https://lwn.net/Articles/224135/).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) To avoid this kind of situation, ensure that all patches within a given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) branch stick closely to the associated topic; a "driver fixes" branch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) should not be making changes to the core memory management code. And, most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) importantly, do not use a git tree to bypass the review process. Post an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) occasional summary of the tree to the relevant list, and, when the time is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) right, request that the tree be included in linux-next.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) If and when others start to send patches for inclusion into your tree,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) don't forget to review them. Also ensure that you maintain the correct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) authorship information; the git "am" tool does its best in this regard, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) you may have to add a "From:" line to the patch if it has been relayed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) you via a third party.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) When requesting a pull, be sure to give all the relevant information: where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) your tree is, what branch to pull, and what changes will result from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) pull. The git request-pull command can be helpful in this regard; it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) format the request as other developers expect, and will also check to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) sure that you have remembered to push those changes to the public server.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Reviewing patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) Some readers will certainly object to putting this section with "advanced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) topics" on the grounds that even beginning kernel developers should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) reviewing patches. It is certainly true that there is no better way to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) learn how to program in the kernel environment than by looking at code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) posted by others. In addition, reviewers are forever in short supply; by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) looking at code you can make a significant contribution to the process as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) whole.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) Reviewing code can be an intimidating prospect, especially for a new kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) developer who may well feel nervous about questioning code - in public -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) which has been posted by those with more experience. Even code written by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) the most experienced developers can be improved, though. Perhaps the best
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) piece of advice for reviewers (all reviewers) is this: phrase review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) comments as questions rather than criticisms. Asking "how does the lock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) get released in this path?" will always work better than stating "the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) locking here is wrong."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Different developers will review code from different points of view. Some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) are mostly concerned with coding style and whether code lines have trailing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) white space. Others will focus primarily on whether the change implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) by the patch as a whole is a good thing for the kernel or not. Yet others
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) will check for problematic locking, excessive stack usage, possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) security issues, duplication of code found elsewhere, adequate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) documentation, adverse effects on performance, user-space ABI changes, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) All types of review, if they lead to better code going into the kernel, are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) welcome and worthwhile.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags