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