How to Keep Pull Requests Manageable

code-reviews.md

How to Keep Pull Requests Manageable

• There are a lot different things you can try to keep pull requests manageable.
• These pointers are not meant to be rules, but merely guidelines when possible. Due to the nature of what you are working on, some of these techniques may not be possible (or incredibly difficult).

• Either way, here are some tips to help make people not want to claw their eyes out reviewing a pull request.

The Basics

• These are the fundamental basics to a pull request and ALL pull requests should have these, regardless of how small or meaningless it is.
• At minimum, you must should include:
  • A descriptive title
  • A brief description of what your pull request is doing in the description
  • What it is trying to solve in the description

Keep the issue you are working on small

• Tickets for large and wide-ranging feature requests will result in big unwieldy pull requests.
• Conversely, small and narrow feature requests will result in small manageable pull requests.
• If the ticket you were working on is "Create all of Accounts Receivable", your pull request is going to be humongous!
• TL;DR: Get ahead of the problem and make the tickets narrow and specific.

Keep your pull requests small but have many of them

• If the ticket you are working on is large, then break it down yourself into smaller manageable, logical, tickets.
• You can either do this yourself by creating subtasks in JIRA or on your own by submitting a series of pull requests that complete the larger ticket.
• Branch off of your branches when you want to start a new PR. Git is fully capable to managing your code across branches.
• TL;DR: Break your work up into multiple pull requests.

Keep your commits functionally logical

• Sometimes you are just going to have large pull requests.
• One technique to review large pull requests is on a commit-by-commit basis.
• This allows the reviewer to take smaller digestible chunks of the pull request.
• To aid in this style of reviewing, you need to make your commits functionally logical and commit message descriptive.
• TL;DR Keep commits narrow and functionally logical (features + tests) with descriptive commit messages.

How to do this

When making a commit, try to do the following:

• Make the commit message descriptive and clear.

  • One technique to use is to start the commit message with a verb follow by a brief description of what I did.
  • To add further context, prefix the message with the ticket code.
  • For example: [INV-1234] Adds validation for recurring invoice start date.

• Make the committed content the minimum vertical slice of functionality.

  • If you add a small feature, include the unit tests for that feature in the same commit.
  • This makes it easier for the code reviewer to understand your change.
  • When you include unit tests within the same context as your feature change, you will avoid review comments such as:

• Even if you wrote the whole feature, don't be afraid to commit your work in smaller chunks.

  • Git UI tools make this easier to do because you can commit only specific lines and stage a series of commits before pushing.

  • GitHub Desktop is useful for switching between repositories and branches. It lets you select specific lines for commit. It unfortunately does not have staged-commit features.

  • GitX-dev has very detailed graphing of branches and the flow of commits. It also lets you stage commits before pushing. It unfortunately does not make switching repositories very easy.

TL;DR

• Make the tickets narrow and specific.
• Break your work up into multiple pull requests.
• Keep commits narrow and functionally logical (features + tests) with descriptive commit messages.

help