GitHub pull request tips to improve your git workflow
In this post I’ll outline some GitHub pull request tips to improve your git workflow that will make managing pull requests a better experience.
A pull request should be small and enforce the single responsibility principle; as in the “S” in “SOLID”. If your pull request is too complex, separate functional components into multiple pull requests.
Create a pull request template for your repository. This will help users fill in important information when creating a new pull request.
Provide import information in a pull request description, answering the following questions:
- How? / What does it do?
- How is this code built?
- How was the code tested?
- How is this code deployed?
- What task tracking story is this associated with (JIRA, Pivotal Tracker, etc)?
If the feature change can be shown visually, provide a screenshot or GIF. I use LICEcap to capture functionality in an animated GIF.
Integrate your Github project with continuous integration service(s); example: Jenkins, CodeShip, CircleCI, Travis. A pull request should have a successful build before it is reviewed by your team.
- Use descriptive commit messages
- Provide unit tests for each new feature
- Avoid unnecessary code changes (diffs) by determining code formatting best practices with your team and implement linters to enforce. Style guides can be implemented for your IDE and text editor. Linters and code analyzers can be set to fail a CI build when the code does not conform to your rules.
- Example Ruby style guide
- Example code analyzer Rubocop
- If necessary, a pull request can be set to ignore whitespace changes by adding
?w=1to the URL
Use code blocks and syntax highlighting to make code comments more legible (using triple backticks).
Use tasks lists in your pull request description to track progress.
Fully utilize the functionality in the discussion sidebar. Request reviewers relevant to your project and utilize the pull request reviews workflow. Assign team members to a pull request who are responsible. Define workflow labels to track the status of a pull request (ex: On hold, Do not review, help wanted).
Mention @somebody in comments to involve another Github user in conversation.
As a reviewer of a pull request, add inline code comments from the Files changed tab. Additional commits can be pushed to the PR branch. When the feedback has been addressed, click on “Resolve conversation” from the Conversation tab. A running conversation on a pull request is good collaboration, and the history can be helpful in the future. When the pull request has been approved, ensure to squash all commits and rebase before merging.