1 .. _development_followthrough: 1 .. _development_followthrough:
2 2
3 Followthrough 3 Followthrough
4 ============= 4 =============
5 5
6 At this point, you have followed the guideline 6 At this point, you have followed the guidelines given so far and, with the
7 addition of your own engineering skills, have 7 addition of your own engineering skills, have posted a perfect series of
8 patches. One of the biggest mistakes that eve 8 patches. One of the biggest mistakes that even experienced kernel
9 developers can make is to conclude that their 9 developers can make is to conclude that their work is now done. In truth,
10 posting patches indicates a transition into th 10 posting patches indicates a transition into the next stage of the process,
11 with, possibly, quite a bit of work yet to be 11 with, possibly, quite a bit of work yet to be done.
12 12
13 It is a rare patch which is so good at its fir 13 It is a rare patch which is so good at its first posting that there is no
14 room for improvement. The kernel development 14 room for improvement. The kernel development process recognizes this fact,
15 and, as a result, is heavily oriented toward t 15 and, as a result, is heavily oriented toward the improvement of posted
16 code. You, as the author of that code, will b 16 code. You, as the author of that code, will be expected to work with the
17 kernel community to ensure that your code is u 17 kernel community to ensure that your code is up to the kernel's quality
18 standards. A failure to participate in this p 18 standards. A failure to participate in this process is quite likely to
19 prevent the inclusion of your patches into the 19 prevent the inclusion of your patches into the mainline.
20 20
21 21
22 Working with reviewers 22 Working with reviewers
23 ---------------------- 23 ----------------------
24 24
25 A patch of any significance will result in a n 25 A patch of any significance will result in a number of comments from other
26 developers as they review the code. Working w 26 developers as they review the code. Working with reviewers can be, for
27 many developers, the most intimidating part of 27 many developers, the most intimidating part of the kernel development
28 process. Life can be made much easier, though 28 process. Life can be made much easier, though, if you keep a few things in
29 mind: 29 mind:
30 30
31 - If you have explained your patch well, revi 31 - If you have explained your patch well, reviewers will understand its
32 value and why you went to the trouble of wr 32 value and why you went to the trouble of writing it. But that value
33 will not keep them from asking a fundamenta 33 will not keep them from asking a fundamental question: what will it be
34 like to maintain a kernel with this code in 34 like to maintain a kernel with this code in it five or ten years later?
35 Many of the changes you may be asked to mak 35 Many of the changes you may be asked to make - from coding style tweaks
36 to substantial rewrites - come from the und 36 to substantial rewrites - come from the understanding that Linux will
37 still be around and under development a dec 37 still be around and under development a decade from now.
38 38
39 - Code review is hard work, and it is a relat 39 - Code review is hard work, and it is a relatively thankless occupation;
40 people remember who wrote kernel code, but 40 people remember who wrote kernel code, but there is little lasting fame
41 for those who reviewed it. So reviewers ca 41 for those who reviewed it. So reviewers can get grumpy, especially when
42 they see the same mistakes being made over 42 they see the same mistakes being made over and over again. If you get a
43 review which seems angry, insulting, or out 43 review which seems angry, insulting, or outright offensive, resist the
44 impulse to respond in kind. Code review is 44 impulse to respond in kind. Code review is about the code, not about
45 the people, and code reviewers are not atta 45 the people, and code reviewers are not attacking you personally.
46 46
47 - Similarly, code reviewers are not trying to 47 - Similarly, code reviewers are not trying to promote their employers'
48 agendas at the expense of your own. Kernel 48 agendas at the expense of your own. Kernel developers often expect to
49 be working on the kernel years from now, bu 49 be working on the kernel years from now, but they understand that their
50 employer could change. They truly are, alm 50 employer could change. They truly are, almost without exception,
51 working toward the creation of the best ker 51 working toward the creation of the best kernel they can; they are not
52 trying to create discomfort for their emplo 52 trying to create discomfort for their employers' competitors.
53 53
54 - Be prepared for seemingly silly requests fo 54 - Be prepared for seemingly silly requests for coding style changes
55 and requests to factor out some of your cod 55 and requests to factor out some of your code to shared parts of
56 the kernel. One job the maintainers do is t 56 the kernel. One job the maintainers do is to keep things looking
57 the same. Sometimes this means that the cle 57 the same. Sometimes this means that the clever hack in your driver
58 to get around a problem actually needs to b 58 to get around a problem actually needs to become a generalized
59 kernel feature ready for next time. 59 kernel feature ready for next time.
60 60
61 What all of this comes down to is that, when r 61 What all of this comes down to is that, when reviewers send you comments,
62 you need to pay attention to the technical obs 62 you need to pay attention to the technical observations that they are
63 making. Do not let their form of expression o 63 making. Do not let their form of expression or your own pride keep that
64 from happening. When you get review comments 64 from happening. When you get review comments on a patch, take the time to
65 understand what the reviewer is trying to say. 65 understand what the reviewer is trying to say. If possible, fix the things
66 that the reviewer is asking you to fix. And r 66 that the reviewer is asking you to fix. And respond back to the reviewer:
67 thank them, and describe how you will answer t 67 thank them, and describe how you will answer their questions.
68 68
69 Note that you do not have to agree with every 69 Note that you do not have to agree with every change suggested by
70 reviewers. If you believe that the reviewer h 70 reviewers. If you believe that the reviewer has misunderstood your code,
71 explain what is really going on. If you have 71 explain what is really going on. If you have a technical objection to a
72 suggested change, describe it and justify your 72 suggested change, describe it and justify your solution to the problem. If
73 your explanations make sense, the reviewer wil 73 your explanations make sense, the reviewer will accept them. Should your
74 explanation not prove persuasive, though, espe 74 explanation not prove persuasive, though, especially if others start to
75 agree with the reviewer, take some time to thi 75 agree with the reviewer, take some time to think things over again. It can
76 be easy to become blinded by your own solution 76 be easy to become blinded by your own solution to a problem to the point
77 that you don't realize that something is funda 77 that you don't realize that something is fundamentally wrong or, perhaps,
78 you're not even solving the right problem. 78 you're not even solving the right problem.
79 79
80 Andrew Morton has suggested that every review 80 Andrew Morton has suggested that every review comment which does not result
81 in a code change should result in an additiona 81 in a code change should result in an additional code comment instead; that
82 can help future reviewers avoid the questions 82 can help future reviewers avoid the questions which came up the first time
83 around. 83 around.
84 84
85 One fatal mistake is to ignore review comments 85 One fatal mistake is to ignore review comments in the hope that they will
86 go away. They will not go away. If you repos 86 go away. They will not go away. If you repost code without having
87 responded to the comments you got the time bef 87 responded to the comments you got the time before, you're likely to find
88 that your patches go nowhere. 88 that your patches go nowhere.
89 89
90 Speaking of reposting code: please bear in min 90 Speaking of reposting code: please bear in mind that reviewers are not
91 going to remember all the details of the code 91 going to remember all the details of the code you posted the last time
92 around. So it is always a good idea to remind 92 around. So it is always a good idea to remind reviewers of previously
93 raised issues and how you dealt with them; the 93 raised issues and how you dealt with them; the patch changelog is a good
94 place for this kind of information. Reviewers 94 place for this kind of information. Reviewers should not have to search
95 through list archives to familiarize themselve 95 through list archives to familiarize themselves with what was said last
96 time; if you help them get a running start, th 96 time; if you help them get a running start, they will be in a better mood
97 when they revisit your code. 97 when they revisit your code.
98 98
99 What if you've tried to do everything right an 99 What if you've tried to do everything right and things still aren't going
100 anywhere? Most technical disagreements can be 100 anywhere? Most technical disagreements can be resolved through discussion,
101 but there are times when somebody simply has t 101 but there are times when somebody simply has to make a decision. If you
102 honestly believe that this decision is going a 102 honestly believe that this decision is going against you wrongly, you can
103 always try appealing to a higher power. As of 103 always try appealing to a higher power. As of this writing, that higher
104 power tends to be Andrew Morton. Andrew has a 104 power tends to be Andrew Morton. Andrew has a great deal of respect in the
105 kernel development community; he can often unj 105 kernel development community; he can often unjam a situation which seems to
106 be hopelessly blocked. Appealing to Andrew sh 106 be hopelessly blocked. Appealing to Andrew should not be done lightly,
107 though, and not before all other alternatives 107 though, and not before all other alternatives have been explored. And bear
108 in mind, of course, that he may not agree with 108 in mind, of course, that he may not agree with you either.
109 109
110 110
111 What happens next 111 What happens next
112 ----------------- 112 -----------------
113 113
114 If a patch is considered to be a good thing to 114 If a patch is considered to be a good thing to add to the kernel, and once
115 most of the review issues have been resolved, 115 most of the review issues have been resolved, the next step is usually
116 entry into a subsystem maintainer's tree. How 116 entry into a subsystem maintainer's tree. How that works varies from one
117 subsystem to the next; each maintainer has his 117 subsystem to the next; each maintainer has his or her own way of doing
118 things. In particular, there may be more than 118 things. In particular, there may be more than one tree - one, perhaps,
119 dedicated to patches planned for the next merg 119 dedicated to patches planned for the next merge window, and another for
120 longer-term work. 120 longer-term work.
121 121
122 For patches applying to areas for which there 122 For patches applying to areas for which there is no obvious subsystem tree
123 (memory management patches, for example), the 123 (memory management patches, for example), the default tree often ends up
124 being -mm. Patches which affect multiple subs 124 being -mm. Patches which affect multiple subsystems can also end up going
125 through the -mm tree. 125 through the -mm tree.
126 126
127 Inclusion into a subsystem tree can bring a hi 127 Inclusion into a subsystem tree can bring a higher level of visibility to a
128 patch. Now other developers working with that 128 patch. Now other developers working with that tree will get the patch by
129 default. Subsystem trees typically feed linux 129 default. Subsystem trees typically feed linux-next as well, making their
130 contents visible to the development community 130 contents visible to the development community as a whole. At this point,
131 there's a good chance that you will get more c 131 there's a good chance that you will get more comments from a new set of
132 reviewers; these comments need to be answered 132 reviewers; these comments need to be answered as in the previous round.
133 133
134 What may also happen at this point, depending 134 What may also happen at this point, depending on the nature of your patch,
135 is that conflicts with work being done by othe 135 is that conflicts with work being done by others turn up. In the worst
136 case, heavy patch conflicts can result in some 136 case, heavy patch conflicts can result in some work being put on the back
137 burner so that the remaining patches can be wo 137 burner so that the remaining patches can be worked into shape and merged.
138 Other times, conflict resolution will involve 138 Other times, conflict resolution will involve working with the other
139 developers and, possibly, moving some patches 139 developers and, possibly, moving some patches between trees to ensure that
140 everything applies cleanly. This work can be 140 everything applies cleanly. This work can be a pain, but count your
141 blessings: before the advent of the linux-next 141 blessings: before the advent of the linux-next tree, these conflicts often
142 only turned up during the merge window and had 142 only turned up during the merge window and had to be addressed in a hurry.
143 Now they can be resolved at leisure, before th 143 Now they can be resolved at leisure, before the merge window opens.
144 144
145 Some day, if all goes well, you'll log on and 145 Some day, if all goes well, you'll log on and see that your patch has been
146 merged into the mainline kernel. Congratulati 146 merged into the mainline kernel. Congratulations! Once the celebration is
147 complete (and you have added yourself to the M 147 complete (and you have added yourself to the MAINTAINERS file), though, it
148 is worth remembering an important little fact: 148 is worth remembering an important little fact: the job still is not done.
149 Merging into the mainline brings its own chall 149 Merging into the mainline brings its own challenges.
150 150
151 To begin with, the visibility of your patch ha 151 To begin with, the visibility of your patch has increased yet again. There
152 may be a new round of comments from developers 152 may be a new round of comments from developers who had not been aware of
153 the patch before. It may be tempting to ignor 153 the patch before. It may be tempting to ignore them, since there is no
154 longer any question of your code being merged. 154 longer any question of your code being merged. Resist that temptation,
155 though; you still need to be responsive to dev 155 though; you still need to be responsive to developers who have questions or
156 suggestions. 156 suggestions.
157 157
158 More importantly, though: inclusion into the m 158 More importantly, though: inclusion into the mainline puts your code into
159 the hands of a much larger group of testers. 159 the hands of a much larger group of testers. Even if you have contributed
160 a driver for hardware which is not yet availab 160 a driver for hardware which is not yet available, you will be surprised by
161 how many people will build your code into thei 161 how many people will build your code into their kernels. And, of course,
162 where there are testers, there will be bug rep 162 where there are testers, there will be bug reports.
163 163
164 The worst sort of bug reports are regressions. 164 The worst sort of bug reports are regressions. If your patch causes a
165 regression, you'll find an uncomfortable numbe 165 regression, you'll find an uncomfortable number of eyes upon you;
166 regressions need to be fixed as soon as possib 166 regressions need to be fixed as soon as possible. If you are unwilling or
167 unable to fix the regression (and nobody else 167 unable to fix the regression (and nobody else does it for you), your patch
168 will almost certainly be removed during the st 168 will almost certainly be removed during the stabilization period. Beyond
169 negating all of the work you have done to get 169 negating all of the work you have done to get your patch into the mainline,
170 having a patch pulled as the result of a failu 170 having a patch pulled as the result of a failure to fix a regression could
171 well make it harder for you to get work merged 171 well make it harder for you to get work merged in the future.
172 172
173 After any regressions have been dealt with, th 173 After any regressions have been dealt with, there may be other, ordinary
174 bugs to deal with. The stabilization period i 174 bugs to deal with. The stabilization period is your best opportunity to
175 fix these bugs and ensure that your code's deb 175 fix these bugs and ensure that your code's debut in a mainline kernel
176 release is as solid as possible. So, please, 176 release is as solid as possible. So, please, answer bug reports, and fix
177 the problems if at all possible. That's what 177 the problems if at all possible. That's what the stabilization period is
178 for; you can start creating cool new patches o 178 for; you can start creating cool new patches once any problems with the old
179 ones have been taken care of. 179 ones have been taken care of.
180 180
181 And don't forget that there are other mileston 181 And don't forget that there are other milestones which may also create bug
182 reports: the next mainline stable release, whe 182 reports: the next mainline stable release, when prominent distributors pick
183 up a version of the kernel containing your pat 183 up a version of the kernel containing your patch, etc. Continuing to
184 respond to these reports is a matter of basic 184 respond to these reports is a matter of basic pride in your work. If that
185 is insufficient motivation, though, it's also 185 is insufficient motivation, though, it's also worth considering that the
186 development community remembers developers who 186 development community remembers developers who lose interest in their code
187 after it's merged. The next time you post a p 187 after it's merged. The next time you post a patch, they will be evaluating
188 it with the assumption that you will not be ar 188 it with the assumption that you will not be around to maintain it
189 afterward. 189 afterward.
190 190
191 191
192 Other things that can happen 192 Other things that can happen
193 ----------------------------- 193 -----------------------------
194 194
195 One day, you may open your mail client and see 195 One day, you may open your mail client and see that somebody has mailed you
196 a patch to your code. That is one of the adva 196 a patch to your code. That is one of the advantages of having your code
197 out there in the open, after all. If you agre 197 out there in the open, after all. If you agree with the patch, you can
198 either forward it on to the subsystem maintain 198 either forward it on to the subsystem maintainer (be sure to include a
199 proper From: line so that the attribution is c 199 proper From: line so that the attribution is correct, and add a signoff of
200 your own), or send an Acked-by: response back 200 your own), or send an Acked-by: response back and let the original poster
201 send it upward. 201 send it upward.
202 202
203 If you disagree with the patch, send a polite 203 If you disagree with the patch, send a polite response explaining why. If
204 possible, tell the author what changes need to 204 possible, tell the author what changes need to be made to make the patch
205 acceptable to you. There is a certain resista 205 acceptable to you. There is a certain resistance to merging patches which
206 are opposed by the author and maintainer of th 206 are opposed by the author and maintainer of the code, but it only goes so
207 far. If you are seen as needlessly blocking g 207 far. If you are seen as needlessly blocking good work, those patches will
208 eventually flow around you and get into the ma 208 eventually flow around you and get into the mainline anyway. In the Linux
209 kernel, nobody has absolute veto power over an 209 kernel, nobody has absolute veto power over any code. Except maybe Linus.
210 210
211 On very rare occasion, you may see something c 211 On very rare occasion, you may see something completely different: another
212 developer posts a different solution to your p 212 developer posts a different solution to your problem. At that point,
213 chances are that one of the two patches will n 213 chances are that one of the two patches will not be merged, and "mine was
214 here first" is not considered to be a compelli 214 here first" is not considered to be a compelling technical argument. If
215 somebody else's patch displaces yours and gets 215 somebody else's patch displaces yours and gets into the mainline, there is
216 really only one way to respond: be pleased tha 216 really only one way to respond: be pleased that your problem got solved and
217 get on with your work. Having one's work shov 217 get on with your work. Having one's work shoved aside in this manner can
218 be hurtful and discouraging, but the community 218 be hurtful and discouraging, but the community will remember your reaction
219 long after they have forgotten whose patch act 219 long after they have forgotten whose patch actually got merged.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.