Pull Requests - It's all about the details

Let’s talk about pull requests. Most people I know operate through a PR system at work. The basic process goes like this:

1. Write code
2. Push up the branch and create a pull request
3. Put a few details in the description about what changes were made
4. Wait for comments
5. Improve code based on comments if needed
6. Ship it

The description portion of the Pull Request can be incredibly important though in making sure your code is reviewed effectively and getting better comments. This is something I’ve been focusing on personally recently and that we’ve been focusing on more as a team. Even though putting more thought and effort into crafting a pull request takes a little more time, it helps us QA much more effectively and allows us to have better context when reviewing each other’s code.

So here are some quick tips to crafting effective PRs.

First, start with user stories. This is something I only recently started doing but it basically acts as a summary of what is going on in english. As a ___, when I ___, I want to see ___.

Example:

As a developer,

When I go to the github repo’s readme

I want to see clear instructions to get set up

As a developer,

When I go to the github repo’s readme

I want the setup instructions to work

Second, what happened bullet points. This is just an overview of the biggest changes. It should potentially re-iterate some of your git commit history but not all of it. If you’re still working on creating a clear git commit history with small, specific commits, this section might be a little bigger. 

Third, screen shots. To take a screenshot of a specific portion of a screen, on a mac, you use SHIFT + CMD + 4. It’s often helpful to annotate that screenshot by placing arrows or text onto the image. An easy way to do this is to open the screenshot, open the toolbox, and place the arrow shape into the image and then save it. You can see where all these things are below.

Open Toolbox

Select Shape

Select arrow option

Fourth, record video or screencast. I’m not great at recording a demo video but screencasts can be really helpful. RecordIt was recommended to me and it’s been great so far. It’s really simple to understand, use, and post where necessary. 

Fifth, Add QA instructions as a checklist. At my company, developers do a pretty in depth QA of each other’s issues in addition to code review. Creating a QA checklist also helps you as a developer think through possible edge cases or flag critical paths that need a more in depth look. This QA checklist should be specific, include links and then what should be seen. It’s often easiest to make this as a checklist so that whoever is QA’ing can just check off the items as the QA. The example below is VERY simple, but hopefully it is easy to imagine what instructions for a more complex feature or bug fix might look like.

Example:

Go to www.allisonsherenmcmillan.blogspot.com and sign in as an admin

Go to the consulting tab

[ ] You should see bold headlines

Sign out of the admin role

Go to the consulting tab

[ ] You should still see the bold headlines

Sixth, add labels in Github. This is more in reference to the code review processSome of the labels we use include things like “Ready for improvement”, “Don’t merge or review”, etc. Sometimes if I don’t have time to complete the description for a PR, I’ll just temporarily slap a “Don’t merge or review” label on there until I can complete it.

Finally, open your PR and get excited for some great feedback. By spending more time on your PR description, you'll get better feedback and you'll be able to ship more confidently.