6.1.Working with reviewers¶

A patch of any significance will result in a number of comments from otherdevelopers as they review the code. Working with reviewers can be, formany developers, the most intimidating part of the kernel developmentprocess. Life can be made much easier, though, if you keep a few things inmind:

• If you have explained your patch well, reviewers will understand itsvalue and why you went to the trouble of writing it. But that valuewill not keep them from asking a fundamental question: what will it belike 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 tweaksto substantial rewrites - come from the understanding that Linux willstill 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 famefor those who reviewed it. So reviewers can get grumpy, especially whenthey see the same mistakes being made over and over again. If you get areview which seems angry, insulting, or outright offensive, resist theimpulse to respond in kind. Code review is about the code, not aboutthe 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 tobe working on the kernel years from now, but they understand that theiremployer could change. They truly are, almost without exception,working toward the creation of the best kernel they can; they are nottrying to create discomfort for their employers’ competitors.

• Be prepared for seemingly silly requests for coding style changesand requests to factor out some of your code to shared parts ofthe kernel. One job the maintainers do is to keep things lookingthe same. Sometimes this means that the clever hack in your driverto get around a problem actually needs to become a generalizedkernel feature ready for next time.

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 aremaking. Do not let their form of expression or your own pride keep thatfrom happening. When you get review comments on a patch, take the time tounderstand what the reviewer is trying to say. If possible, fix the thingsthat 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 byreviewers. If you believe that the reviewer has misunderstood your code,explain what is really going on. If you have a technical objection to asuggested change, describe it and justify your solution to the problem. Ifyour explanations make sense, the reviewer will accept them. Should yourexplanation not prove persuasive, though, especially if others start toagree with the reviewer, take some time to think things over again. It canbe easy to become blinded by your own solution to a problem to the pointthat you don’t realize that something is fundamentally wrong or, perhaps,you’re not even solving the right problem.

Andrew Morton has suggested that every review comment which does not resultin a code change should result in an additional code comment instead; thatcan help future reviewers avoid the questions which came up the first timearound.

One fatal mistake is to ignore review comments in the hope that they willgo away. They will not go away. If you repost code without havingresponded to the comments you got the time before, you’re likely to findthat your patches go nowhere.

Speaking of reposting code: please bear in mind that reviewers are notgoing to remember all the details of the code you posted the last timearound. So it is always a good idea to remind reviewers of previouslyraised issues and how you dealt with them; the patch changelog is a goodplace for this kind of information. Reviewers should not have to searchthrough list archives to familiarize themselves with what was said lasttime; if you help them get a running start, they will be in a better moodwhen they revisit your code.

What if you’ve tried to do everything right and things still aren’t goinganywhere? Most technical disagreements can be resolved through discussion,but there are times when somebody simply has to make a decision. If youhonestly believe that this decision is going against you wrongly, you canalways try appealing to a higher power. As of this writing, that higherpower tends to be Andrew Morton. Andrew has a great deal of respect in thekernel development community; he can often unjam a situation which seems tobe hopelessly blocked. Appealing to Andrew should not be done lightly,though, and not before all other alternatives have been explored. And bearin 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 oncemost of the review issues have been resolved, the next step is usuallyentry into a subsystem maintainer’s tree. How that works varies from onesubsystem to the next; each maintainer has his or her own way of doingthings. In particular, there may be more than one tree - one, perhaps,dedicated to patches planned for the next merge window, and another forlonger-term work.

For patches applying to areas for which there is no obvious subsystem tree(memory management patches, for example), the default tree often ends upbeing -mm. Patches which affect multiple subsystems can also end up goingthrough the -mm tree.

Inclusion into a subsystem tree can bring a higher level of visibility to apatch. Now other developers working with that tree will get the patch bydefault. Subsystem trees typically feed linux-next as well, making theircontents 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 ofreviewers; these comments need to be answered as in the previous round.

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 worstcase, heavy patch conflicts can result in some work being put on the backburner so that the remaining patches can be worked into shape and merged.Other times, conflict resolution will involve working with the otherdevelopers and, possibly, moving some patches between trees to ensure thateverything applies cleanly. This work can be a pain, but count yourblessings: before the advent of the linux-next tree, these conflicts oftenonly 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 beenmerged into the mainline kernel. Congratulations! Once the celebration iscomplete (and you have added yourself to the MAINTAINERS file), though, itis 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. Theremay be a new round of comments from developers who had not been aware ofthe patch before. It may be tempting to ignore them, since there is nolonger any question of your code being merged. Resist that temptation,though; you still need to be responsive to developers who have questions orsuggestions.

More importantly, though: inclusion into the mainline puts your code intothe hands of a much larger group of testers. Even if you have contributeda driver for hardware which is not yet available, you will be surprised byhow 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 aregression, you’ll find an uncomfortable number of eyes upon you;regressions need to be fixed as soon as possible. If you are unwilling orunable to fix the regression (and nobody else does it for you), your patchwill almost certainly be removed during the stabilization period. Beyondnegating 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 couldwell make it harder for you to get work merged in the future.

After any regressions have been dealt with, there may be other, ordinarybugs to deal with. The stabilization period is your best opportunity tofix these bugs and ensure that your code’s debut in a mainline kernelrelease is as solid as possible. So, please, answer bug reports, and fixthe problems if at all possible. That’s what the stabilization period isfor; you can start creating cool new patches once any problems with the oldones have been taken care of.

And don’t forget that there are other milestones which may also create bugreports: the next mainline stable release, when prominent distributors pickup a version of the kernel containing your patch, etc. Continuing torespond to these reports is a matter of basic pride in your work. If thatis insufficient motivation, though, it’s also worth considering that thedevelopment community remembers developers who lose interest in their codeafter it’s merged. The next time you post a patch, they will be evaluatingit with the assumption that you will not be around to maintain itafterward.

6.3.Other things that can happen¶

One day, you may open your mail client and see that somebody has mailed youa patch to your code. That is one of the advantages of having your codeout there in the open, after all. If you agree with the patch, you caneither forward it on to the subsystem maintainer (be sure to include aproper From: line so that the attribution is correct, and add a signoff ofyour own), or send an Acked-by: response back and let the original postersend it upward.

If you disagree with the patch, send a polite response explaining why. Ifpossible, tell the author what changes need to be made to make the patchacceptable to you. There is a certain resistance to merging patches whichare opposed by the author and maintainer of the code, but it only goes sofar. If you are seen as needlessly blocking good work, those patches willeventually flow around you and get into the mainline anyway. In the Linuxkernel, nobody has absolute veto power over any code. Except maybe Linus.

On very rare occasion, you may see something completely different: anotherdeveloper posts a different solution to your problem. At that point,chances are that one of the two patches will not be merged, and “mine washere first” is not considered to be a compelling technical argument. Ifsomebody else’s patch displaces yours and gets into the mainline, there isreally only one way to respond: be pleased that your problem got solved andget on with your work. Having one’s work shoved aside in this manner canbe hurtful and discouraging, but the community will remember your reactionlong after they have forgotten whose patch actually got merged.