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.

Searching through logs

Recently, I needed to check out which endpoints in a specific version of our api were being hit/ if they were being hit at all. This involves searching through the paper trail logs, which was an interesting process so I thought I’d write about it.

First, I want to say, there is a better path than the one I took. It wasn’t until after I did all this log downloading and searching that I discovered the paper trail CLI. I haven’t had a chance to take a deep dive into it yet, but I assume using it is better than downloading 30 days of log files and than combining them into 1 log file.

Which is what I did first. I had to look at 30 days worth of logs, so I went to the paper trail heroku add-on and downloaded all 30 days worth of logs. Then I used cat *.tsv >merged.tsv to put all of the 30 files into 1 file. After that, I checked which endpoints I needed to look at by just looking at the routes file. Luckily, there are a pretty finite number of endpoints for the specific version I was looking at. I think, if I was dealing with significantly more endpoints, i’d need to figure out a better systems for ensuring that I’ve checked all the endpoints.

Then, for the simple endpoints (ie- /livestreams or /livestreams.json for the index endpoint or /livestreams/ for the show endpoints) I just ran a simple grep -c command which greps for that path and then counts it. For example cat FILE_PATH | grep -c /v1/livestreams.json.

When I got to a slightly more complex endpoint, for example, one that had a path like /v1/livestreams/something_unique_here/watched I couldn’t just grep for the endpoint, I needed to use a grep compatible regex to find the number of results that had “watched” at the end. I did this by searching cat FiLE_PATH | grep -c ‘/watched\b’ which looks only for the last bit of the url.

And that’s it. Pretty simple but I hadn’t handled searching through large log files or any sort of complex grepping before.