docs / cl_respect.md [blame]

# Respectful Changes
## A Guide for Code Authors

_For the code reviewer counterpart, see
__[Respectful Code Reviews](cr_respect.md)__._

## Set up for success

#### Do the pre-work

Help challenging code reviews go smoothly by reaching out to prospective
reviewers before writing any code. Describing the problem and your approach
ahead of time reduces surprise and provides an opportunity for early input.
Ensure the decisions resulting from these exchanges, as well as the reasoning
behind them, are accessible to others (e.g. via bug or design doc).

#### Mind your reviewer

Make choices that spare your reviewer time or cognitive load, such as preferring
a series of short changes to a massive one, or uploading separate patches to
isolate rebases during review.

#### Satisfy preconditions

Ensure your code is ready for review before you send it: it should compile, have
adequate testing that passes, and respect the style guide (using _git cl
format/lint_ is encouraged). Consider validating this by performing a
self-review. This is respectful of reviewer time and can sometimes save you a
review round trip. If you're looking for an early review that's fine too, but
please say so.

#### Remember communication can be hard

Differences in understanding or opinions are to be expected in the context of
code reviews. Always assume competence and goodwill. Don't hesitate to suggest a
quick meeting (face-to-face or via VC); sometimes it's much faster to resolve an
issue that way than email ping pong.

## Request the review

#### Choose your reviewers

Give thought to whether you want to serialize or parallelize your reviews. If
you're new to the codebase, it's a good idea to do a first round with a single
local reviewer to clear the basic issues. Try to limit the number of owners you
solicit (only one per section), but ensure you pick sufficiently specialized
ones. Finally, be mindful of time zones and their effect on the review cycle
time. Picking the right reviewers comes with experience, but you can start by
looking at OWNERS files, asking a teammate, or using tools ('_git cl owners_',
[Chromite Butler](https://chrome.google.com/webstore/detail/chromite-butler/bhcnanendmgjjeghamaccjnochlnhcgj)).

#### Provide context

Change descriptions are the first impression your change makes, both on
reviewers and on code archeologists from the future. A [good description](contributing.md#Uploading-a-change-for-review)
aims to do two things. First, it conveys at a glance the high level view.
Second, it provides references to all the relevant information for a deep dive:
design docs, bugs, testing instructions. The bug\# is a useful reference, but
isn't sufficient on its own. Summarize **what** and **why** in the description.
You can additionally provide guidance on how to do the review in the e-mailed
message.

#### State your expectations

When sending the review, be clear to your reviewer about your expectations. In
terms of the review, this means specifying the kind of reviewing (e.g., high
level) as well as who should review what using which level of scrutiny. In terms
of timing, this means stating your deadline or lack thereof. For tight
deadlines, be convinced your urgency is real (hint: should be rare), and
communicate its reason, as well as your intent to land required follow up
refactorings.

## During the review

#### Expect responsiveness

Getting your code reviewed is about getting unblocked. You should expect
reviewer input within 1 business day. This should however be modulated based on
the size, complexity, urgency / importance of your change, as well as on
time zone differences. Beyond that, double check the reviewer's code review tool
nickname (e.g. "_jdoe (OOO til 4 Apr)_"), their calendar and ping them on IM. If
that fails, look for another reviewer.

#### Address all comments

Be convinced your reviewers feel all comments have been addressed before you
commit. Questions are addressed by providing an answer. Suggestions can be
addressed in one of three ways: adopt it immediately ("Done."), defer it to a
subsequent change (TODO with a bug \#) or push back with additional
information. Whenever more information is required, make sure everyone agrees on
the problem before you discuss the solution and consider expanding the
documentation.

#### Wait for LGTM from all your reviewers

As a general rule of thumb, if a reviewer has made a comment on your CL, even
though you may have addressed that comment in a new patchset, don't submit the
CL until you have their LGTM, unless the reviewer gave the OK to do so (e.g.
when the reviewer delegates the reviewing task to someone else). If you need to
land a CL urgently and one of your reviewers isn't available (e.g. OOO), submit
your CL, and send your reviewer a note; in the note, be sure to include the
reason why you had to land the CL, and show that you've considered their
opinions & are ready to promptly act on their additional comments in a followup
CL.

#### What to do if it's going wrong

Code reviews should not make you feel bad. If you find yourself in that
situation, or you feel the review's at an impasse, don't attempt to work around
a reviewer but take a step back. A face to face meeting or a VC can sometimes
help unblock a review. If this doesn't sound like an option, or simply if you
feel you need to talk about it, reach out to someone you trust.

## After the review

Code reviews are in large part about having others watch your back. Don't
hesitate to say "Thank you" once the review is completed. Additionally, if
you're new to code reviews, take a few moments to reflect on what went well or
didn't.