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.

Example file: .github/pull_request_template.md, contents:

**Task Link:**

**Why:**

**How:**

**Screenshot(s):**

Provide import information in a pull request description, answering the following questions:

• Why?
• 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.

Code tips:

• 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=1 to the URL

Use code blocks and syntax highlighting to make code comments more legible (using triple backticks).

```ruby
s3_key = "person/#{person_id}.json"
s3_object = s3.bucket(s3_bucket).object(s3_key)
s3_object.upload_file(file_path)
```

Or:

```bash
# to build:
./gradlew clean build

# to execute tests:
./gradlew :sub-project:test --tests "MyNewFeature"
```

Preview:

Use tasks lists in your pull request description to track progress.

TODO:
- [ ] Fix build failures
- [x] This is a completed task
- [ ] Address feedback from Eric

Preview:

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.

# checkout branch to merge into
git checkout master

# ensure you have the latest commits
git pull

# checkout your branch
git checkout some-dev-branch

# squash last 5 commits interactively. replace "pick" with "s" to squash, or "f" to fixup (which ignores your commit message)
git rebase -i HEAD~5

# rebase on parent branch
git rebase master

# merge single commit
git checkout master
git merge some-dev-branch

# push to remote
git push

# delete local dev branch
git branch -d some-dev-branch

# delete remote dev branch
git push origin :some-dev-branch