Respectful review comments in open source
Good contributing guides explain why and show how
Symfony's contribution guidelines contains a section called Respectful Review Comments - it gives specific details for using language when commenting on pull requests and issues.
I think it’s amazing!
Giving positive feedback
The section on Giving Positive Feedback gives clear guidance (and examples!) of how to behave and what to say.
"When you prepare your comment, consider the amount of work and time the author has spent on their idea and how your response would make them feel."
The guide sets the standard for acceptable behavior in the community, but also it's just plain helpful for reviewers and contributors because it breaks things down into actionable steps.
- Use words like "please" and "thank you".
- Assume everyone is well-meaning.
- Ask for clarification.
- Suggest an alternative.
I like how it puts the focus on encouraging contributions rather than getting into the blame-game.
Be thankful for their work (so far), stay positive and really help them to make the contribution a great one. Especially if they are a first time contributor.
Receiving feedback positively
In the contributing guide at The Good Docs Project, we have a section on accepting feedback from others. I really like how it covers feelings:
- “It’s normal to feel nervous….”
- “Try to give each comment the benefit of the doubt and seriously consider it.”
- ”Remember to be positive and show appreciation when people take time to review your drafts.”
Humans have feelings too
So much of giving and receiving feedback is laden with emotion. It's really helpful when contributing guides cover the soft skills for dealing with digital and asynchronous human interaction.
Do you know of other open source contributing guides that articulate this kind of positive approach to review comments? Please let me know!
Image credit: Teddy photo by Anastasiia Krutota on Unsplash.