Tips for Opening Pull-Requests

There are many tips on how to define the code review process and how to perform reviews. I want to share tips on opening a pull request so it is easier for you and your code reviewer.

Comments on your pull requests are privilege.
Receiving many comments does not imply that you have done a poor job.
It means your code is understandable enough and inspired someone to give you suggestions.

It's common for developers to feel discouraged when they receive comments on their code review. 

However, good pull requests invite comments. Most people won't bother to properly review code that they don't understand and just mark it as "looks fine".

Here are my tips for opening good pull requests:

1. Open small feature sliced pull-requests

2. Record a video walkthrough of the feature

3. Code review your code

4. Have a structured name and description

5. Have a review buddy

Let’s break these down.

1/ Open small feature sliced pull-requests

Since Github doesn't support Stacked Diffs, the PRs I open go directly to the main branch.

I'm a heavy user of Feature Toggles. They allow me to split work on the feature and deploy it before it is ready for public consumption.

I open at least 1 pull request daily when working on a feature.

Avoid opening pull requests by layer - one pull request for database migrations, then for the backend, then for the front end, and finally for tests. Often, when you get to the front end, you might notice that your database structure needs to be adjusted. 

I prefer to split pull requests into feature slices containing a part of a feature implemented end to end.

For large features, I use the "diagram as todo" technique, where I have a diagram representing the flow of the feature and color-code which parts of the feature are read and which are being worked on. 

• Green - feature slice that is done

• Yellow - feature slice in this pull request

• White - feature slice to be done

• Gray / Red - feature slice that won't be implemented

I include a screenshot of the diagram in the pull request description

You can learn more about this "diagram as todo" technique" 👉 here.

2/ Record a video walkthrough of the feature

💡 I think this is the most important tip from this post.

Before opening a pull request for review, I record a video walkthrough of this feature. There, I explain the feature and go through it. 

I currently use Loom for this purpose.

I have done it so many times that now, I need 1 take, and in 3~4 minutes, I can explain even the most complex features.

I can't count how often I start recording and notice a small bug or UI/UX issue. 🤩

I will share a link to this video in the pull request's description

When the feature is deployed, I share it in Slack with the rest of the team.

In Angry Building, we have a `#changelog` channel where I share the Loom videos with the whole company.

Afterward, our support team shares these videos with customers who would benefit from the new features.

Our marketing team will use those videos to compile our changelog email for customers.

3/ Code review your code

After I'm done with Loom, I perform a self-code review. This has also helped me to catch a lot of issues before sending my code to be reviewed by others 🕵️‍♂️

I go through the PR, pretending I didn't write it. I review it the same way I'll review someone else's pull request.

I look at every file and mark it as "Viewed" (later, if I need to make changes, this will help me to see what I have changed).

I even add comments if I need to provide extra context.

I added questions in places where I'm not sure about the approach.

4/ Have a structured name and description

I prefix related pull requests with the name of the domain or feature. So things are grouped.

Here are a couple of examples:

[Teams] Invite modal
[Teams] Invite email flow
[Topics] Assign to product
[Topics] Index page
[Funds] Transfer via transaction
[Funds] Change transaction fund
[Funds] Move between funds

For the pull request description, I used the following template in my projects:

[Ticket link](https://link-to-external-system)

[Description]

[Loom video]

## Screenshots

## Code improvements

• Ticket link to Trello, Asana, Jira, or whatever project management system is used

• Description includes

  • What is this pull request for

  • Implementation details

  • Embedded screenshot of a  diagram as todo

• Loom video from tip 2

• Screenshots, when user-facing feature

  • desktop and mobile versions

• Code improvements

  • List of system-level changes included as part of this pull-request

    • Example: “Extracted new SelectList generic React component”

  • Sometimes, those can be split into separate pull request

5/ Have review buddy

When working with small pull requests, reviewers can often lose the thread and miss the bigger picture. 

Because of this, I work closely with someone on my team to be my "buddy" reviewer for a bigger feature. I always wait for this person to merge my PRs and communicate with them about my features. 

Even if this person is not directly involved in my project, I leverage their perspective as a sounding board from day 1. Their insights and input help refine my work and ensure it's on the right track

Conclusion

Your job is to make your pull request good enough to receive comments. Good pull requests invite comments. A lot of the tips here sound like "too much work". However, with practice, those become second nature. 

If you have any questions or comments, you can ping me on Threads, LinkedIn, Mastodon, Twitter or just leave a comment below 📭