If you are using a released version of Kubernetes, you should refer to the docs that go with that version.
The latest release of this document can be found [here](http://releases.k8s.io/release-1.3/docs/devel/faster_reviews.md).Documentation for other releases can be found at releases.k8s.io.
Most of what is written here is not at all specific to Kubernetes, but it bears being written down in the hope that it will occasionally remind people of "best practices" around code reviews.
You've just had a brilliant idea on how to make Kubernetes better. Let's call that idea "FeatureX". Feature X is not even that complicated. You have a pretty good idea of how to implement it. You jump in and implement it, fixing a bunch of stuff along the way. You send your PR - this is awesome! And it sits. And sits. A week goes by and nobody reviews it. Finally someone offers a few comments, which you fix up and wait for more review. And you wait. Another week or two goes by. This is horrible.
What went wrong? One particular problem that comes up frequently is this - your PR is too big to review. You've touched 39 files and have 8657 insertions. When your would-be reviewers pull up the diffs they run away - this PR is going to take 4 hours to review and they don't have 4 hours right now. They'll get to it later, just as soon as they have more free time (ha!).
Let's talk about how to avoid this.
Are you sure FeatureX is something the Kubernetes team wants or will accept, or that it is implemented to fit with other changes in flight? Are you willing to bet a few days or weeks of work on it? If you have any doubt at all about the usefulness of your feature or the design - make a proposal doc (in docs/proposals; for example the QoS proposal) or a sketch PR (e.g., just the API or Go interface) or both. Write or code up just enough to express the idea and the design and why you made those choices, then get feedback on this. Be clear about what type of feedback you are asking for. Now, if we ask you to change a bunch of facets of the design, you won't have to re-write it all.
Small PRs get reviewed faster and are more likely to be correct than big ones. Let's face it - attention wanes over time. If your PR takes 60 minutes to review, I almost guarantee that the reviewer's eye for details is not as keen in the last 30 minutes as it was in the first. This leads to multiple rounds of review when one might have sufficed. In some cases the review is delayed in its entirety by the need for a large contiguous block of time to sit and read your code.
Whenever possible, break up your PRs into multiple commits. Making a series of discrete commits is a powerful way to express the evolution of an idea or the different ideas that make up a single feature. There's a balance to be struck, obviously. If your commits are too small they become more cumbersome to deal with. Strive to group logically distinct ideas into commits.
For example, if you found that FeatureX needed some "prefactoring" to fit in, make a commit that JUST does that prefactoring. Then make a new commit for FeatureX. Don't lump unrelated things together just because you didn't think about prefactoring. If you need to, fork a new branch, do the prefactoring there and send a PR for that. If you can explain why you are doing seemingly no-op work ("it makes the FeatureX change easier, I promise") we'll probably be OK with it.
Obviously, a PR with 25 commits is still very cumbersome to review, so use common sense.
If you can extract whole ideas from your PR and send those as PRs of their own, you can avoid the painful problem of continually rebasing. Kubernetes is a fast-moving codebase - lock in your changes ASAP, and make merges be someone else's problem.
Obviously, we want every PR to be useful on its own, so you'll have to use common sense in deciding what can be a PR vs what should be a commit in a larger PR. Rule of thumb - if this commit or set of commits is directly related to FeatureX and nothing else, it should probably be part of the FeatureX PR. If you can plausibly imagine someone finding value in this commit outside of FeatureX, try it as a PR.
Don't worry about flooding us with PRs. We'd rather have 100 small, obvious PRs than 10 unreviewable monoliths.
Often, as you are implementing FeatureX, you find things that are just wrong. Bad comments, poorly named functions, bad structure, weak type-safety. You should absolutely fix those things (or at least file issues, please) - but not in this PR. See the above points - break unrelated changes out into different PRs or commits. Otherwise your diff will have WAY too many changes, and your reviewer won't see the forest because of all the trees.
Read up on GoDoc - follow those general rules. If you're writing code and you think there is any possible chance that someone might not understand why you did something (or that you won't remember what you yourself did), comment it. If you think there's something pretty obvious that we could follow up on, add a TODO. Many code-review comments are about this exact issue.
Nothing is more frustrating than doing a review, only to find that the tests are inadequate or even entirely absent. Very few PRs can touch code and NOT touch tests. If you don't know how to test FeatureX - ask! We'll be happy to help you design things for easy testing or to suggest appropriate test cases.
If you find yourself writing something that touches a lot of modules, think hard about the dependencies you are introducing between packages. Can some of what you're doing be made more generic and moved up and out of the FeatureX package? Do you need to use a function or type from an otherwise unrelated package? If so, promote! We have places specifically for hosting more generic code.
Likewise if FeatureX is similar in form to FeatureW which was checked in last month and it happens to exactly duplicate some tricky stuff from FeatureW, consider prefactoring core logic out and using it in both FeatureW and FeatureX. But do that in a different commit or PR, please.
Your reviewer has finally sent you some feedback on FeatureX. You make a bunch of changes and ... what? You could patch those into your commits with git "squash" or "fixup" logic. But that makes your changes hard to verify. Unless your whole PR is pretty trivial, you should instead put your fixups into a new commit and re-push. Your reviewer can then look at that commit on its own - so much faster to review than starting over.
We might still ask you to clean up your commits at the very end, for the sake of a more readable history, but don't do this until asked, typically at the point where the PR would otherwise be tagged LGTM.
General squashing guidelines:
-
Sausage => squash
When there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state and commit message for the whole PR.
-
Layers => don't squash
When there are independent changes layered upon each other to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate PRs, but there's really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn't immediately get out of date.
A commit, as much as possible, should be a single logical change. Each commit should always have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended. Do not link pull requests by # in a commit description, because GitHub creates lots of spam. Instead, reference other PRs via the PR your commit is in.
Sometimes we need to remind each other of core tenets of software design - Keep It Simple, You Aren't Gonna Need It, Minimum Viable Product, and so on. Adding features "because we might need it later" is antithetical to software that ships. Add the things you need NOW and (ideally) leave room for things you might need later - but don't implement them now.
We understand that it is hard to imagine, but sometimes we make mistakes. It's OK to push back on changes requested during a review. If you have a good reason for doing something a certain way, you are absolutely allowed to debate the merits of a requested change. You might be overruled, but you might also prevail. We're mostly pretty reasonable people. Mostly.
So, you've done all that and you still aren't getting any PR love? Here's some things you can do that might help kick a stalled process along:
-
Make sure that your PR has an assigned reviewer (assignee in GitHub). If this is not the case, reply to the PR comment stream asking for one to be assigned.
-
Ping the assignee (@username) on the PR comment stream asking for an estimate of when they can get to it.
-
Ping the assignee by email (many of us have email addresses that are well published or are the same as our GitHub handle @google.com or @redhat.com).
-
Ping the team (via @team-name) that works in the area you're submitting code.
If you think you have fixed all the issues in a round of review, and you haven't heard back, you should ping the reviewer (assignee) on the comment stream with a "please take another look" (PTAL) or similar comment indicating you are done and you think it is ready for re-review. In fact, this is probably a good habit for all PRs.
One phenomenon of open-source projects (where anyone can comment on any issue) is the dog-pile - your PR gets so many comments from so many people it becomes hard to follow. In this situation you can ask the primary reviewer (assignee) whether they want you to fork a new PR to clear out all the comments. Remember: you don't HAVE to fix every issue raised by every person who feels like commenting, but you should at least answer reasonable comments with an explanation.
Obviously, none of these points are hard rules. There is no document that can take the place of common sense and good taste. Use your best judgment, but put a bit of thought into how your work can be made easier to review. If you do these things your PRs will flow much more easily.