Skip to content

Instantly share code, notes, and snippets.

@emmanuelnk
Forked from sktse/code-reviews.md
Created October 8, 2021 06:19
Show Gist options
  • Save emmanuelnk/1f039e28ddf6a60c911c04fa4384d034 to your computer and use it in GitHub Desktop.
Save emmanuelnk/1f039e28ddf6a60c911c04fa4384d034 to your computer and use it in GitHub Desktop.
How to Keep Pull Requests Manageable

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).

More like guidelines

  • 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

Don't be this guy

Keep the issue you are working on small

  • Tickets for large and wide-ranging feature requests will result in big unwieldy pull requests. Complicated!
  • 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! Bad idea
  • TL;DR: Get ahead of the problem and make the tickets narrow and specific.

Keep your pull requests small but have many of them

Break things up

  • 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

No idea

When making a commit, try to do the following:

  • Make the commit message descriptive and clear. What is going on?

    • 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:

screen shot 2017-04-03 at 11 14 35 am

  • 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. githubdesktop

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

gitx-dev

TL;DR

Summary

  • 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment