Blame view

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