Hey, open sourcer! 😊 I’ve heard through the digital webs that you’ve become quite the wordsmith when it comes to giving feedback on pull requests and want to learn something new.
No worries, I’ve been there myself when I started getting more comfortable in the open source world. So, grab a chair, your favorite snack or beverage (I highly recommend water. It’s fresh and good for you! 😉), and your notebook (or in this case, your laptop). Because I’m about to share five techniques that will have you reviewing pull requests like a boss.
Neil deGrasse Tyson says "Let's Do This!" to give you confidence!
Feedback Technique 1: The “Show and Tell” Review
For this technique, you provide screenshots or links to other sources that help explain the benefit of the new approach that you’re suggesting to your fellow contributor. Here's how it's done:
First, take a screenshot of the thing you want to convey in your feedback. I highly recommend using Fireshot. It's an easy way to take screenshots on your computer.
This is a GIF of someone taking a screenshot of an image via a Mac
Then, go to the repository of your choosing and click on Pull Requests
A yellow circle surrounds the third tab called "Pull Requests". Click there to pick the PR you want to review.
Once you pick the pull request you want to review, click on Files Changed:
Add your comments, then drag and drop your image in the textbox.
In a textbox,
Click Submit review and volià you're done! 😊
There's a green button saying "Submit Review". Click on it after you finish your review.
In my experience, this type of review is helpful when giving feedback on pull requests that require adding a feature to an open source project's website (for example a logo) or an image on one of its Markdown files. It can help the person see how their contribution impacts the overall project.
It's like if you were watching a commercial for a facial soap and you see the scenes where they show close ups of how the product makes your skin healthier. Showing someone an image of what needs fixing can help convey what's going on more clearly.
Speaking of skin, here's another strategy where your shifting powers, I mean adaptability skills, can be helpful.
Feedback Technique 2: The “Chameleon” Review
The “Chameleon” is a feedback giving technique where you adapt your PR review based on the type of contribution that your peer is making. It's like how a chameleon changes their skin color to fit in with their surroundings (minus the hiding from predators part of course 😉).
For example, if you’re reviewing a pull request that's text-based like the one in the image below, I highly recommend giving feedback via dialogic questions (for example, how does this resource stand out from other courses that teach JavaScript?).
This technique is helpful because it encourages the recipient of your review to think deeply about their contribution. It also teaches you how to tailor your feedback based on the type of pull request that you are reviewing.
Now that you know the Chameleon, the next technique you'll learn is one that can help you swipe through fields, I mean, long lines of code.
Feedback Technique 3: Two Peas in a Pod
The “Two Peas in a pod” is a PR review technique where you comment on one line of code in the conversation while another contributor gives feedback on another line code in the same pull request.
Here's an example:
Two contributors comment on one line of code
My comment on a different line of code on the same pull request
As shown in the first picture, it's helpful to point out why certain methods won't work and discuss some alternatives the pull requester can use. Additionally, consider commenting on a different way to improve the PR once you picked the line of code you want to improve.
When using this method, I highly recommend encouraging you and your fellow reviewer to pick a line of code that suits your strengths because it'll make giving feedback easier.
Since my background is in writing and education, I decided to comment on the text-based line that you see in the second picture whereas the other contributors focused on improving the image element due to being more experienced in coding.
This method helps you develop your written communication skills and ultimately makes reviewing pull requests less stressful. That's two benefits for the price of one! 😊 Cool right? 😉
Speaking of lessening your stress, I have another strategy that will have you reviewing pull requests like the Flash from The Justice League!
Feedback Technique 4: Teach’em Review
This “Teach’em” review is a PR review technique where you pretty much instruct your peer on how to improve their PR instead of just pointing out the issues in the PR.
Here are some examples:
My suggestion: turning the <div> element into a more semantic HTML element.
I give tips to the contributor how to make their code-based contributions more accessible
When using this technique, I highly recommend pointing out an area of improvement. Then, you can briefly teach a strategy they could use in the future.
This approach can help improve your coding skills and develop your written communication skills, which is very useful in the world of tech.
Now, there’s just one more technique that will help you upgrade your PR reviewing skills.
Feedback Technique 5: The “Suggestion” Review
If you're focusing on other open source projects, have a deadline for an assignment, or you're just tired from a long day at work but want to review pull requests, this feedback giving technique will be the ultimate tool in your open sourcer kit. It focuses on giving constructive feedback through your review.
Here's how it's done:
- Click on the Files Changed tab of a person’s pull request:
There are four tabs underneath a person's pull request. The final one "Files changed" is circled in yellow. That's the tab you pick in the first step
- Hover over the line of code you want to review and click on the blue plus sign:
There is a blue plus sign over the line code that has a yellow covering. This indicates that you have picked a line of code you want to review.
- Click on the file icon that has a plus on top and a minus sign on the bottom:
- Rewrite the line of code, improving it as you think is necessary:
There's a yellow arrow point to an area that says ```suggestion. This where you rewrite the line of code that you choose to review.
- Click on Add Single Comment
There is a yellow arrow pointing at the "Add single comment" button. This is what you click on to insert your suggestion into the person's line of code.
- Write your comment in the textbox, click on Request Changes, and Submit Review.
The first arrow points to a textbox, the place where type your comment. The second arrow points the last radio button labeled "Request Changes". The final arrow points at a green button labeled "Submit review".
I highly recommend using this feedback technique for pull requests that are text-based because it will show your suggestion to the person who made the pull request, which is especially helpful if you are too tired or don't have time to give a brief grammar lesson (trust me, I've been there).
Like the other feedback techniques I previously mentioned, the suggestion review can also help you improve your detail-oriented skills as it encourages you to think of the best way to convey your feedback. It's pretty awesome! 😊
Conclusion
Congratulations, you now have five feedback giving techniques in your Open Sourcer toolkit!
Before I let you go, I want you to remember this. Open source contributions begin and end with you, so use your powers wisely. Now, go out there and be the best pull request reviewer in open source!
Deadpool and his crew is walking slowly towards their next challenge. Be like Deadpool with your pull request reviews! :)
Credits
Let's Do This GIF by National Geographic
Super Hero Walking GIF by 20th Century Fox Home Entertainment
Screenshot GIF from "How to Take a Screenshot on a MacBook" by Hung Nguyen