On 2024-08-21 15:18:12 +0000 (+0000), Jeremy Stanley wrote: [...]
The most common themes reported by those struggling to contribute are not related to tooling or workflow confusion, but instead seem to come down to basic communication challenges. [...]
Last week, Jens mentioned this article in IRC: https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatte... Coincidentally published the same day I posted the first message in this thread, it's an amusing semi-satirical look at many of the same challenges our community has also identified. A quick summary of the author's points (though I strongly encourage you to check out the full article if you have time): * Batch up review feedback and try not to "move goalposts" by repeatedly coming up with new problems in subsequent reviews that you could have found the first time through (i.e. don't just stop reviewing on the first issue you find). * Don't demand a change author include unrelated fixes to nearby code (pointing it out as optional in case they want to tackle it if they have time is fine, just be clear it's not a requirement of approval). * Try to reach a consensus of opinion with other reviewers on the same changes/project, and avoid jerking the author around by changing your own opinion on things. * If a proposed implementation is unsuitable, be clear about what kind of alternative implementation would be suitable. * Lead with the most important problems in a change, not the trivial ones. * When reviewing individual changes that are part of a larger approved specification, try to focus on whether those changes implement the spec as written regardless of whether you agree with choices the project has made within the spec (if you disagree, get the spec changed or amended first). * Extremes of opinion can always be found to reject a change, so look for a position of compromise when possible. * Be cautious and deliberate about shifts of expectation over time, since authors are prone to replicate patterns from prior changes and existing code. I think articles like this help to confirm we're on the right track, and I find it a reassuring reminder that these are challenges pretty much all communities struggle with. We're not alone. If we can come up with viable approaches for improving the situation, we'll be helping not just our own community, but open source software projects everywhere. Also, a quick reminder: If you'll be in Suwon for OpenInfra Summit Asia or Indianapolis for OpenInfra Days North America, come to the forum session (Bridging the Gap: Community and Contributing Orgs). Whether or not you're available for the in-person sessions, replies to this mailing list thread can help refine the community's approach to contributor communications so we can start to get some of these things documented in relevant places (Contributor Guide, Project Team Guide, et cetera). -- Jeremy Stanley