How to write a great pull request

This post was originally a TweetStorm. Read that tweetstorm.


Why you should write great pull requests

Having strong git skills are essential as a developer. Leveling up these skills involves a diverse set of talents.

One area where I feel there’s room for easy improvement is within contextual and descriptive pull requests.

By including additional context you make the life of those reviewing your pull request easier, enabling faster and better code review.

What to include

In my pull requests I like to include a lot context. This would include some of the following headers:

1. A link to the ticket

This is always helpful as a way to connect the different methods of communication that your company uses within your Product Development teams.

2. A description of the ticket

Explain potential changes in the code or away from the original intent of the story.

This may be a synthesis of offline discussions you had surrounding the code you wrote. It could include what decisions were made, or realizations come to surrounding necessary codebase changes.

3. Why you made these changes

I like think of this from a users perspective. This could look like a User Story

“A User should be able to do X”

Again this creates further clarification around the purpose for this pull request, which can result in stronger suggestions from those reviewing your code. Potentially even highlighting miscommunication or stimulating debate around what the original ticket was supposed to mean.

4. How you went about changing this functionality This could be said to be redundant due to your great git history but including it here prevents some simple context switching between the git history and your PR documentation.

5. Risk

Risk involved with this pull request. Are you changing the primary login or payment gateway? Well let’s make sure this doesn’t blow up

Not to belabor a point, but you can also include

6. QA plan

7. Links to documentation/specs

8. Links to what you used as a model

9. Screenshots

10. If it’s a Partial PR include, To-Do’s that you’re working toward

These are all useful things to include, and will hopefully make suggestions against your pull request easier.

Luckily, Github has taken the steps to allow repo administrator the ability to add pull request and issue templates to their repo’s consider including this in your company’s repo.

Consider using the raw version of the template I included for a starting point on your repo’s PR template.

Inciting discussion on your Pull Request

After opening the pull request it’s important to get feedback on it.

Rather than making people give you suggestions, include comments and questions about things or thoughts you had while writing this PR.

Could this have been done better?

I thought to add another test here.

Should I raise an error here?

Could this query be faster/simpler?

I’ve also done these as notes within the code itself, just as a way to keep track of my thoughts while writing the code itself. For these internal notes, I’ll highlight them by including a PR Line Note referencing my comment or further explaining my comment.

This engages your reviewer so they’ll go ahead and answer questions rather than just giving you a :shipit: also you’ll learn!

Next, be sure to let your team know there’s a PR up and you’d like a review. Maybe even assign or mention specific domain experts.

Open the original ticket and link to your PR and then move your story along in the pipeline, if that’s in your org’s process.

Now.. Bask in the glory of a PR well done before going to back to share the wealth and reviewing someone else’s pull request.

Additional Resources

  1. Template for writing a great PR

  2. Issue and Pull Request templates

Thoughts on content distribution

At what point does distribution of content have diminishing returns?

Recently, I’ve started to tweetstorm, I do so in order to quickly gather feedback, create an open conversation and most significantly to execute on writing with the method I’d use “if it looked easy”.

I hope to write more about this soon.

From that initial creation, those tweetstorms usually continue to progress as posts on my personal website. Eventually I share the now edited, fleshed out tweetstorm/blog posts again across the relevant networks.

As I continue doing so, I’ve been thinking about the balance between distribution of a single similar piece of content, versus creation of new content.

Contrasting this, does “saying” the same thing 8 times seem useful?

I can reduce some of this speculation by deciding on a metric of success. That too will be a moving target. Tweetstorms, for now I just want to see someone engage with my stream of conscious which tells me what to turn into posts or include in newsletters. For a Medium post, a recommendation. For LinkedIn, perhaps its a greater flow of incoming opportunities.

There’s the opportunity to test against these metrics. I can find the time spent creating and distributing this singular piece of content against engagement with said content or my other measures of success.

Continuing along this though process, it would appear beneficial to learn what mediums work best for your works. Then how you can reach those metrics most with those different mediums.

I see folks that can create an initial video about a topic. That becomes a podcast, 1+ blog posts, maybe a conference talk, and screencast. Thats 4 different mediums. Each with potential to be distributed to 2 unique networks tailored to that type of content.

Single individuals can start with this time-intensive process and move to work with others to create these multiple forms of content.

You could initiate this through Periscope or Snapchat (ala Mark Suster or Justin Kan) and end up with screencasts, blogs, slideshows, videos.

Mark Suster specifically is re-envisioning portions of his old content into easily digestable snapchat stories. Begging the question, should I go back and turn old content into new mediums, or distribute it in new places?

Are we all still distributing content as a means to become some “domain expert” or just to “show our work”, again “it depends”.

On Twitter versus LinkedIn versus Medium versus my Personal Site, I want you to:

Adding `git squash` to my git workflow

This post was originally a TweetStorm. Read that tweetstorm.

This post is part of a group I’ve written about improving your version control skills.


I’m pretty sure that squashing commits is now going to be a part of my git workflow. I’ve had some serious level ups in my git workflow as I’ve continued working as a developer. This is definitely one of them.

The habit of regular small (even trivial) commits, was baked into me while going through Dev Bootcamp in Chicago with regular commit intervals on the half hour. I further cemented this by including a tool in my terminal prompt that told me the time since my last commit on my current branch, similar to what @Goles has written here for the Zsh terminal.

picture credit to Tuo Huang from this post

Eventually I learned of git commit patch and Gitx. I previously wrote about git committing interactively.

Some folks told me I was potentially making my commits too small! This is were git squash -ing becomes so useful.

With git squash in your VCS toolbelt it doesn’t matter that I wrote 1 commit every 30 minutes. Or turned an hour’s worth of work into 4 commits. Sometimes that story needs to be editing, which is where git squash comes in.

Now after my full git log of commits I can go back and edit.

git commit drunk, git squash sober

Git squash allows you to turn the three commits into one for that test you wrote. Or to turn the passing test and the correctly method into one single commit.

Allows you to totally remove an unused piece of git history, like the comment you added asking a question, which was then answered within the code review process on your great pull request.

Allows you to amend the first and second and third of a 30 commit git branch not just the last commit.

You can turn your Hobbit trilogy into the one movie it should’ve been, without that non-canon love triangle.

Now you might be asked to do this when contributing to Open Source Software or just opening a pull request against your team’s branch or repo.

Git squashing also pairs well with git cherry-picking. They are are similar, yet different skills. So check out git squashing and add it to your repertoire of git skills.

Additional Resources

  1. Github : @goles zsh_git_timer

  2. Git tip: show current branch and time elapsed since last commit in command line by Tuo Huang