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