code review is best understood as a form of teaching, not just a procedural obstacle.
we were originally going to talk about how code review can be mentorship, but we realized as we wrote that at the moment, most of the stuff we know how to explain are the more negative, complain-y parts about how to keep it from being an obstacle. so, we're doing that, instead!
before we do that, though... first off, thanks for reading! this is the first substantive post here on Leaves that wasn't originally written somewhere else. we had no idea whether we'd ever feel the spontaneous urge to post here, but it seems that enough of Cohost lives in our heart that we do. :)
.... since we do spend time thinking about the poetry of all this, we'd also like to mention that it has been pointed out to us that the metaphor of "post" is at odds with the "leaves" thing. we agree that that's true, but we don't know what to do about it just yet.
okay, back to the topic. so, as most of you probably know, we're ex-Google. we want to emphasize that, although we're going to say nice things about Gerrit, it's not our goal to shill for our former employer here. just, the code review tool is genuinely a good one, for reasons we'll get into in a sec. it does have maintainers and a governing body that isn't just purely google people; most notably, the Wikimedia Foundation uses it heavily. Gerrit is heavily inspired by Google's internal system, Critique, but it is not the same codebase and it stands on its own.
it honestly makes us feel kind of icky to be still using tooling that has its history bound up with our abusive alma mater, but, like... it's good tooling. okay. that's out of the way, now on to the good stuff!
we've spoken at length, but mostly in private, about why we don't like github-style code review UX
the short explanation is that gerrit facilitates conversations that are close-to-the-code and that actually progress to some sort of conclusion. the github-style model (imitated by gitlab and many of the more recent forges) does neither.
gerrit does this by having UI designed around the code listing as the primary navigation mechanism, while also treating comment threads as first-class objects that can be navigated in a variety of other ways when the situation calls for it.
the data model is BARELY different from the github one, it's all about the UI affordances
there was an occasion three years ago when we ran a political conversation in a github pull request.... that was not fun. we did it because we had to; it was the only permitted venue for that project's governance decisions. fortunately most code review is easier than that, but it made some things very clear to us.
in any sort of contentious, many-way discussion, it's vital that people who are trying to read themselves in later actually be able to do so
to this end, there are two critical needs:
that second one is hard because some meanie-butts-for-heads actively try to construct context that exists only between themselves and the person they seek to oppress, so that they can say horrible shit but sound reasonable to bystanders. this is one reason that political discussions often seem to suddenly change topic - only the principals to it know what the connection is.
one of our primary goals in running such discussions is always to spread that context to as many people as possible, both people following along in-the-moment and people catching up later.
github slices each comment sub-thread into its own small-print view which is collapsed by default. it also elides everything but the beginning and the end of the top-level chronological timeline. finally, and this is the worst part, there's no way to see EVERYTHING in chronological order - only each sub-thread. so you can't spot when discussion has been jumping back and forth between sub-threads.
hopefully our explanation of the importance of context makes it clear why we see those things as problems. if not, let us know so we can improve how we talk about it!
keep in mind that, since Microsoft is a hierarchical power structure whose highest incentive is to protect its own existence (the same as all sufficiently large power structures).... silencing dissent presumably feels like the natural and appropriate fix to stakeholders within the company
the victims of structural oppression always have the burden of understanding it more deeply than the perpetrators do, so we wouldn't assume there's any malice or anything, but because of its corporate origin, we don't view github's bad features as accidents. they're the normal sort of thing we expect from tools developed in that setting. if you're not convinced of that, you might find it instructive to consider the ways in which the complaints we've described also apply to Stack Overflow.
these things get embedded structurally... there's a recurring problem where labor organizers at megacorps tend to structure their labor organizations in the ways that the companies themselves are structured, because it was the companies who taught many of us how to run meetings, build working groups, etc
and thus we tend to perpetrate the very oppression we seek to demolish
we can't get into details but it's been interesting to compare notes with friends who've seen that organizing challenge at other companies, because each company has its own slightly different style of corporate bullshit and, thus, so does each union. learning to stop doing that is an ongoing struggle that we can only imagine all megacorp organizers have to deal with.
gerrit, of course, is tooling that originated with google, but somehow it wound up also being a format in which real discussions can take place. we think that probably happened due to the central contradiction in the company's stated values that has led to its current problems, but nobody pays us to worry about google's well-being anymore so we won't get into it...
anyway! if you are someone who reviews other people's code, whether for personal reasons or at work, let us suggest being thoughtful about what tool you use to do that. the medium is the message; you want your code review platform to send messages like "welcome!", "let's learn together", "here's how to do that thing"... not "go away" or "your ideas don't matter". good luck... and let's learn together :)