0001 .. _development_followthrough:
0002
0003 Followthrough
0004 =============
0005
0006 At this point, you have followed the guidelines given so far and, with the
0007 addition of your own engineering skills, have posted a perfect series of
0008 patches. One of the biggest mistakes that even experienced kernel
0009 developers can make is to conclude that their work is now done. In truth,
0010 posting patches indicates a transition into the next stage of the process,
0011 with, possibly, quite a bit of work yet to be done.
0012
0013 It is a rare patch which is so good at its first posting that there is no
0014 room for improvement. The kernel development process recognizes this fact,
0015 and, as a result, is heavily oriented toward the improvement of posted
0016 code. You, as the author of that code, will be expected to work with the
0017 kernel community to ensure that your code is up to the kernel's quality
0018 standards. A failure to participate in this process is quite likely to
0019 prevent the inclusion of your patches into the mainline.
0020
0021
0022 Working with reviewers
0023 ----------------------
0024
0025 A patch of any significance will result in a number of comments from other
0026 developers as they review the code. Working with reviewers can be, for
0027 many developers, the most intimidating part of the kernel development
0028 process. Life can be made much easier, though, if you keep a few things in
0029 mind:
0030
0031 - If you have explained your patch well, reviewers will understand its
0032 value and why you went to the trouble of writing it. But that value
0033 will not keep them from asking a fundamental question: what will it be
0034 like to maintain a kernel with this code in it five or ten years later?
0035 Many of the changes you may be asked to make - from coding style tweaks
0036 to substantial rewrites - come from the understanding that Linux will
0037 still be around and under development a decade from now.
0038
0039 - Code review is hard work, and it is a relatively thankless occupation;
0040 people remember who wrote kernel code, but there is little lasting fame
0041 for those who reviewed it. So reviewers can get grumpy, especially when
0042 they see the same mistakes being made over and over again. If you get a
0043 review which seems angry, insulting, or outright offensive, resist the
0044 impulse to respond in kind. Code review is about the code, not about
0045 the people, and code reviewers are not attacking you personally.
0046
0047 - Similarly, code reviewers are not trying to promote their employers'
0048 agendas at the expense of your own. Kernel developers often expect to
0049 be working on the kernel years from now, but they understand that their
0050 employer could change. They truly are, almost without exception,
0051 working toward the creation of the best kernel they can; they are not
0052 trying to create discomfort for their employers' competitors.
0053
0054 What all of this comes down to is that, when reviewers send you comments,
0055 you need to pay attention to the technical observations that they are
0056 making. Do not let their form of expression or your own pride keep that
0057 from happening. When you get review comments on a patch, take the time to
0058 understand what the reviewer is trying to say. If possible, fix the things
0059 that the reviewer is asking you to fix. And respond back to the reviewer:
0060 thank them, and describe how you will answer their questions.
0061
0062 Note that you do not have to agree with every change suggested by
0063 reviewers. If you believe that the reviewer has misunderstood your code,
0064 explain what is really going on. If you have a technical objection to a
0065 suggested change, describe it and justify your solution to the problem. If
0066 your explanations make sense, the reviewer will accept them. Should your
0067 explanation not prove persuasive, though, especially if others start to
0068 agree with the reviewer, take some time to think things over again. It can
0069 be easy to become blinded by your own solution to a problem to the point
0070 that you don't realize that something is fundamentally wrong or, perhaps,
0071 you're not even solving the right problem.
0072
0073 Andrew Morton has suggested that every review comment which does not result
0074 in a code change should result in an additional code comment instead; that
0075 can help future reviewers avoid the questions which came up the first time
0076 around.
0077
0078 One fatal mistake is to ignore review comments in the hope that they will
0079 go away. They will not go away. If you repost code without having
0080 responded to the comments you got the time before, you're likely to find
0081 that your patches go nowhere.
0082
0083 Speaking of reposting code: please bear in mind that reviewers are not
0084 going to remember all the details of the code you posted the last time
0085 around. So it is always a good idea to remind reviewers of previously
0086 raised issues and how you dealt with them; the patch changelog is a good
0087 place for this kind of information. Reviewers should not have to search
0088 through list archives to familiarize themselves with what was said last
0089 time; if you help them get a running start, they will be in a better mood
0090 when they revisit your code.
0091
0092 What if you've tried to do everything right and things still aren't going
0093 anywhere? Most technical disagreements can be resolved through discussion,
0094 but there are times when somebody simply has to make a decision. If you
0095 honestly believe that this decision is going against you wrongly, you can
0096 always try appealing to a higher power. As of this writing, that higher
0097 power tends to be Andrew Morton. Andrew has a great deal of respect in the
0098 kernel development community; he can often unjam a situation which seems to
0099 be hopelessly blocked. Appealing to Andrew should not be done lightly,
0100 though, and not before all other alternatives have been explored. And bear
0101 in mind, of course, that he may not agree with you either.
0102
0103
0104 What happens next
0105 -----------------
0106
0107 If a patch is considered to be a good thing to add to the kernel, and once
0108 most of the review issues have been resolved, the next step is usually
0109 entry into a subsystem maintainer's tree. How that works varies from one
0110 subsystem to the next; each maintainer has his or her own way of doing
0111 things. In particular, there may be more than one tree - one, perhaps,
0112 dedicated to patches planned for the next merge window, and another for
0113 longer-term work.
0114
0115 For patches applying to areas for which there is no obvious subsystem tree
0116 (memory management patches, for example), the default tree often ends up
0117 being -mm. Patches which affect multiple subsystems can also end up going
0118 through the -mm tree.
0119
0120 Inclusion into a subsystem tree can bring a higher level of visibility to a
0121 patch. Now other developers working with that tree will get the patch by
0122 default. Subsystem trees typically feed linux-next as well, making their
0123 contents visible to the development community as a whole. At this point,
0124 there's a good chance that you will get more comments from a new set of
0125 reviewers; these comments need to be answered as in the previous round.
0126
0127 What may also happen at this point, depending on the nature of your patch,
0128 is that conflicts with work being done by others turn up. In the worst
0129 case, heavy patch conflicts can result in some work being put on the back
0130 burner so that the remaining patches can be worked into shape and merged.
0131 Other times, conflict resolution will involve working with the other
0132 developers and, possibly, moving some patches between trees to ensure that
0133 everything applies cleanly. This work can be a pain, but count your
0134 blessings: before the advent of the linux-next tree, these conflicts often
0135 only turned up during the merge window and had to be addressed in a hurry.
0136 Now they can be resolved at leisure, before the merge window opens.
0137
0138 Some day, if all goes well, you'll log on and see that your patch has been
0139 merged into the mainline kernel. Congratulations! Once the celebration is
0140 complete (and you have added yourself to the MAINTAINERS file), though, it
0141 is worth remembering an important little fact: the job still is not done.
0142 Merging into the mainline brings its own challenges.
0143
0144 To begin with, the visibility of your patch has increased yet again. There
0145 may be a new round of comments from developers who had not been aware of
0146 the patch before. It may be tempting to ignore them, since there is no
0147 longer any question of your code being merged. Resist that temptation,
0148 though; you still need to be responsive to developers who have questions or
0149 suggestions.
0150
0151 More importantly, though: inclusion into the mainline puts your code into
0152 the hands of a much larger group of testers. Even if you have contributed
0153 a driver for hardware which is not yet available, you will be surprised by
0154 how many people will build your code into their kernels. And, of course,
0155 where there are testers, there will be bug reports.
0156
0157 The worst sort of bug reports are regressions. If your patch causes a
0158 regression, you'll find an uncomfortable number of eyes upon you;
0159 regressions need to be fixed as soon as possible. If you are unwilling or
0160 unable to fix the regression (and nobody else does it for you), your patch
0161 will almost certainly be removed during the stabilization period. Beyond
0162 negating all of the work you have done to get your patch into the mainline,
0163 having a patch pulled as the result of a failure to fix a regression could
0164 well make it harder for you to get work merged in the future.
0165
0166 After any regressions have been dealt with, there may be other, ordinary
0167 bugs to deal with. The stabilization period is your best opportunity to
0168 fix these bugs and ensure that your code's debut in a mainline kernel
0169 release is as solid as possible. So, please, answer bug reports, and fix
0170 the problems if at all possible. That's what the stabilization period is
0171 for; you can start creating cool new patches once any problems with the old
0172 ones have been taken care of.
0173
0174 And don't forget that there are other milestones which may also create bug
0175 reports: the next mainline stable release, when prominent distributors pick
0176 up a version of the kernel containing your patch, etc. Continuing to
0177 respond to these reports is a matter of basic pride in your work. If that
0178 is insufficient motivation, though, it's also worth considering that the
0179 development community remembers developers who lose interest in their code
0180 after it's merged. The next time you post a patch, they will be evaluating
0181 it with the assumption that you will not be around to maintain it
0182 afterward.
0183
0184
0185 Other things that can happen
0186 -----------------------------
0187
0188 One day, you may open your mail client and see that somebody has mailed you
0189 a patch to your code. That is one of the advantages of having your code
0190 out there in the open, after all. If you agree with the patch, you can
0191 either forward it on to the subsystem maintainer (be sure to include a
0192 proper From: line so that the attribution is correct, and add a signoff of
0193 your own), or send an Acked-by: response back and let the original poster
0194 send it upward.
0195
0196 If you disagree with the patch, send a polite response explaining why. If
0197 possible, tell the author what changes need to be made to make the patch
0198 acceptable to you. There is a certain resistance to merging patches which
0199 are opposed by the author and maintainer of the code, but it only goes so
0200 far. If you are seen as needlessly blocking good work, those patches will
0201 eventually flow around you and get into the mainline anyway. In the Linux
0202 kernel, nobody has absolute veto power over any code. Except maybe Linus.
0203
0204 On very rare occasion, you may see something completely different: another
0205 developer posts a different solution to your problem. At that point,
0206 chances are that one of the two patches will not be merged, and "mine was
0207 here first" is not considered to be a compelling technical argument. If
0208 somebody else's patch displaces yours and gets into the mainline, there is
0209 really only one way to respond: be pleased that your problem got solved and
0210 get on with your work. Having one's work shoved aside in this manner can
0211 be hurtful and discouraging, but the community will remember your reaction
0212 long after they have forgotten whose patch actually got merged.
