If you have been working in a software team using any type of git workflow, I bet you are familiar with the concept of Pull Requests. This article does not intent to school you on the mechanics of creating it, but rather on the art of what constitutes a Pull Request that brings smiles to reviewers and collaborators alike.

The Title

Here is your opportunity to let the reviewer know what your Pull Request (PR) is all about. Do go beyond just including the issue number; try to reflect the main point of the pull request. Don’t assume the reviewer will know, just based on the issue number.

Examples of Pull Request titles:

  • BOS-8869 Introduced Social Login with Facebook, Google and Twitter
  • MYAPP-0007 Fixed Crash bug when adding item to Calendar in iOS
  • API-1020 Introduced Coach Marks for Filtering

The Description

Putting together a useful description will significantly help the reviewer understand your changes. Specially if you changed many files, or the change is not trivial. Take the time to craft a detailed description, since you are in the best position to justify your approach; after all, you wrote it.

The description field of the Pull Request typically supports some type of markup (i.e.:MarkDown). Just like you would for a well crafted essay, do make use of all of the formatting you have at your disposal to express the ideas in a clear manner.

Examples of Descriptions:

  • Changed implementation of the GetClubDetails method to process the request asynchronously. The return type is now Task<ClubDetail> and the method name GetClubDetailsAsync to follow the convention.
  • Modified the FilterOptionsService to sort options alphabetically.
  • Used the new Location API deployed to Azure and had to change Proxy, Service and Data Transfer Object associated with the Location Screen.

The Screenshots

A picture is worth a thousand words. This could not be more true when it comes to pull requests. If the change involves any UI change, always include a representation of before and after. This saves the reviewer lots of time, and provides clear guidance of what to expect.

Some tips when including screenshots:

  • Resize the image to manageable size. The intent is to provide context of what changed, not to fill the screen with larger than life images.
  • Highlight areas of the UI that are expected to change. Specially if the UI is too busy, and the change cannot be spotted easily.
  • When useful, insert the images into a Table, for the purpose of contrasting the images side to side.

In the end, these are all tips that assist the reviewer in understanding the context of your change, and thus making the review process something that brings a smile to one’s face.