Writing Pull Requests ❤️
Maybe you think that opening a Pull Request is just about clicking buttons (or writing commands 😉). Although you are right, I’m here to convince you that there’s a lot more you can do.
Probably you’ve already gone through that situation where you Pull Request took weeks to be approved and for every single review there was a bunch of discussions to resolve. At that time you may have gotten disappointed (with yourself or with the reviewers), impatient, unconfident, etc and it’s normal. But have you thought about what YOU could have done to prevent all this?
That’s what I’ll talk about today… How YOU can write Pull Requests that tends to be approved faster.
7 things you should do before opening Pull Requests
Give context. Brief and detailed.
Those who will review your changes may not be aware of your goal with them.
Having a nice Pull Request Template (and making sure everyone is filling it) is the best way of give a brief context of your changes.
Besides this, maybe your reviewer want a more detailed explanation. For that you can have a section on you PR to link documents with further details. Here you can have link to documentation, task description (Jira, Trello, ..), RFC, ADR and many others.
Don't mix brief and detailed infos. It increase the chance of reviewer read neither of them.
Self review your changes.
Somewhat obvious.
This doesn't need a lot of explanations, right? If you wan't to learn more about how do better code reviews please refer to this other article [pt-BR] I wrote.
Comment your solution.
Be the first to comment you Pull Request.
— "I've tried X approach but that didn't work because of Y and Z"
— "This way we will have a more consistent approach with the solution we implemented on the <other-service>"
— "What do you think about doing X this way? Although this is more verbose imo this is much more clear than doing Y way"
— "Implemented this based on solution proposed on this article, wdyt?"
— "Not so confident that this is the best way to save this data. Is there any other way to do this?"
Share evidences.
Most of the times the reviewer won't run you code on their local environment (and that doesn't mean their are doing a bad job).
You can help them attaching screenshots, logs with the data being sent to another endpoint, curl commands to staging environment, etc… everything that makes you felt confident when submitting that PR can (and should) be shared with the reviewers.
Link related job.
Your PR may depend on another PR, maybe it's blocking another PR, maybe you are doing this because of changes that happens on another service, maybe it's an infrastructure change request by Cloud Team, etc.
Give your reviewers the chance to know everything you know (not always they will read everything, but if they want you've shared)
Make your tests the documentation
Write tests that are nice to read.
It's not easy but more than write tests that cover the changes you made, write then in a way that they describe your feature behavior.
(Believe me, those strings that we often ignore and have no clear pattern are important for those who are reading your tests)
Keep the codebase consistent
You may want to do something slightly better but different from the rest of codebase is doing. Maybe you shouldn't.
Prefer consistency over this punctual refactors.
Go further, open another PR considering all places that could be refactored with your suggested change.
Conclusion
It's your responsibility make your code changes available on production as soon as possible. You can be tremendous productive writing code, if this code take weeks to go to production you are still inefficient.
Take some time writing your Pull Requests. Do more than I suggested.
You will see the results.
