What is a pull request?
If you work in a smaller team or for an organisation that doesn't use Git then you may not be familiar with a pull request (PR). In short its a brief description of the changes you wish to add to a shared codebase, you are trying to give as much context to the changes as possible to help the development team review your code.
First point of contact - The Title
This is the first thing any developer will read, use it to set the context of your changes and why they are necessary. Keep it short but describe exactly whats happening.
Bad
Better
Good
Clarity is key
The sole purpose of the description you write is to aid the developers reviewing your changes, include as much detail as possible about the updates made. Both as a high level user interface description and also a detailed explanation of any parts of the code changes that may be hard for others to understand.
What to include
A link to feature specification - Generally new features are defined in a format that is linkable to your PR, including this link will allow reviewers to get the full context of the changes made.
A brief summary of the feature spec - If you have made a small change then help out the developers by saving them a click, summarise the changes requested in the PR description. Include the link as well just in case.
The approach you have taken and why - Did you implement your description text using a recursive heuristic algorithm rather than a simple hard coded string? You better explain your reasoning why.
Risk and Areas of concern - Are you not quite sure if the code you have changed will have repercussions elsewhere in the codebase? Its always best to raise this as soon as possible maybe Dave the team rockstar will know more.
Formatting is king
In the land of good PRs the pretty ones always win. As a general statement Markdown is used to format PR descriptions in the main players of Git hosting. Make use of lists, titles, sub-titles, and links. If its easy to read you will be more likely to get a review of your changes.
Images and Gifs
If an image says a thousand words then a Gif says a million. Of course we would say that being associated with a screen recording application on macOS and to be fair images are good for showing static changes to the UI. But if you want to give the full context of a substantial change then a Gif is the way to go, it will set your PRs ahead of the pack and really help the developers see whats happening without running the changes themselves.
Gifable
Gifable is a super-simple screen recording tool that makes GIFs for you in seconds. Record the changes you have made and upload the .gif file to your PR description as an image link.
We hope this blog was helpful, try out the app if you feel it would be useful and happy coding!
Top comments (0)