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/the functionality it provides; 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:

• Added Sorting capabilities: sorting can be done by Category (ascending and descending), by Date Published (Newest and Oldest), and by Amount (Ascending and descending).
• 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.

Bonus Points: Calling out the acceptance criteria of the story, will make it apparent what your change is introducing. Also, call out functionality is not included, in the case where a functionality has been split in several stories.

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.

Sample Pull Request

Title: FITNESS-1039 Add Health Club Class List screen with loading state and booking capabilities.

Description:

The new Class ListScreen provides a list of available classes for the selected Health Club.

• The user sees a loading state while the screen is loading the data from the web.
• The user has the ability to book an available class by tapping on the Book button.
• The user can cancel/reserve a booking, by tapping on the Booked button, for an already booked class.
• Filtering is not implemented.