1# Respectful Changes 2## A Guide for Code Authors 3 4_For the code reviewer counterpart, see 5__[Respectful Code Reviews](cr_respect.md)__._ 6 7## Set up for success 8 9#### Do the pre-work 10 11Help challenging code reviews go smoothly by reaching out to prospective 12reviewers before writing any code. Describing the problem and your approach 13ahead of time reduces surprise and provides an opportunity for early input. 14Ensure the decisions resulting from these exchanges, as well as the reasoning 15behind them, are accessible to others (e.g. via bug or design doc). 16 17#### Mind your reviewer 18 19Make choices that spare your reviewer time or cognitive load, such as preferring 20a series of short changes to a massive one, or uploading separate patches to 21isolate rebases during review. 22 23#### Satisfy preconditions 24 25Ensure your code is ready for review before you send it: it should compile, have 26adequate testing that passes, and respect the style guide (using _git cl 27format/lint_ is encouraged). Consider validating this by performing a 28self-review. This is respectful of reviewer time and can sometimes save you a 29review round trip. If you're looking for an early review that's fine too, but 30please say so. 31 32#### Remember communication can be hard 33 34Differences in understanding or opinions are to be expected in the context of 35code reviews. Always assume competence and goodwill. Don't hesitate to suggest a 36quick meeting (face-to-face or via VC); sometimes it's much faster to resolve an 37issue that way than email ping pong. 38 39## Request the review 40 41#### Choose your reviewers 42 43Give thought to whether you want to serialize or parallelize your reviews. If 44you're new to the codebase, it's a good idea to do a first round with a single 45local reviewer to clear the basic issues. Try to limit the number of owners you 46solicit (only one per section), but ensure you pick sufficiently specialized 47ones. Finally, be mindful of time zones and their effect on the review cycle 48time. Picking the right reviewers comes with experience, but you can start by 49looking at OWNERS files, asking a teammate, or using tools ('_git cl owners_', 50[Chromite Butler](https://chrome.google.com/webstore/detail/chromite-butler/bhcnanendmgjjeghamaccjnochlnhcgj)). 51 52#### Provide context 53 54Change descriptions are the first impression your change makes, both on 55reviewers and on code archeologists from the future. A [good description](https://www.chromium.org/developers/contributing-code#TOC-Writing-change-list-descriptions) 56aims to do two things. First, it conveys at a glance the high level view. 57Second, it provides references to all the relevant information for a deep dive: 58design docs, bugs, testing instructions. The bug\# is a useful reference, but 59isn't sufficient on its own. Summarize **what** and **why** in the description. 60You can additionally provide guidance on how to do the review in the e-mailed 61message. 62 63#### State your expectations 64 65When sending the review, be clear to your reviewer about your expectations. In 66terms of the review, this means specifying the kind of reviewing (e.g., high 67level) as well as who should review what using which level of scrutiny. In terms 68of timing, this means stating your deadline or lack thereof. For tight 69deadlines, be convinced your urgency is real (hint: should be rare), and 70communicate its reason, as well as your intent to land required follow up 71refactorings. 72 73## During the review 74 75#### Expect responsiveness 76 77Getting your code reviewed is about getting unblocked. You should expect 78reviewer input within 1 business day. This should however be modulated based on 79the size, complexity, urgency / importance of your change, as well as on 80time zone differences. Beyond that, double check the reviewer's code review tool 81nickname (e.g. "_jdoe (OOO til 4 Apr)_"), their calendar and ping them on IM. If 82that fails, look for another reviewer. 83 84#### Address all comments 85 86Be convinced your reviewers feel all comments have been addressed before you 87commit. Questions are addressed by providing an answer. Suggestions can be 88addressed in one of three ways: adopt it immediately ("Done."), defer it to a 89subsequent change (TODO with a bug \#) or push back with additional 90information. Whenever more information is required, make sure everyone agrees on 91the problem before you discuss the solution and consider expanding the 92documentation. 93 94#### What to do if it's going wrong 95 96Code reviews should not make you feel bad. If you find yourself in that 97situation, or you feel the review's at an impasse, don't attempt to work around 98a reviewer but take a step back. A face to face meeting or a VC can sometimes 99help unblock a review. If this doesn't sound like an option, or simply if you 100feel you need to talk about it, reach out to someone you trust. 101 102## After the review 103 104Code reviews are in large part about having others watch your back. Don't 105hesitate to say "Thank you" once the review is completed. Additionally, if 106you're new to code reviews, take a few moments to reflect on what went well or 107didn't. 108