Quick People Blog

Useful GitHub patterns

10 Jul 2013

Both my day job and my open-source work involve constant use of git and GitHub. These are some useful patterns that I’ve found myself using regularly.

(From this point onwards, I shall abbreviate a “pull request” as PR).

1. the peel-off PR

when do I use it?

  • I am working on a feature branch
  • I see some injustice in the code that I wish to fix right there and now, but which is unrelated to the feature I’m adding (eg a small bug, inconsistency or coding standards violation)

what I do

  • park my work-in-progress (by either committing or stashing)
  • checkout master
  • create a new branch
  • fix the injustice, open a PR
  • switch back to my feature branch and continue working
  • rebase against the injustice branch later, once it’s been merged

This satisfies both my desire to quickly fix the unrelated problem, and keeps the feature branch clean to make reviewing easier.

2. the optimistic branch

when do I use it?

  • There is an unmerged branch (branch-A) which cannot be merged right now (eg CI build broken, code reviewer busy, etc)
  • I need to make another change that relies on the code in branch-A

what I do

  • create a new branch (branch-B) off branch-A
  • once branch-A is merged into master, I rebase branch-B against master and resolve any resulting conflicts
  • bugfixes from branch-A can then be rebased into branch-B

This approach carries the risk of conflicts if drastic changes are made to branch-A, but the optimistic strategy tends to work out fine in 95% of cases

3. the heads-up PR

when do I use it?

  • I’m making a change that I assume doesn’t really need reviewing
  • I would still like my teammates to know about it

what I do

  • make change on branch
  • raise a PR
  • merge the PR myself immediately

This methods doesn’t block me from carrying on, but GitHub still notifies my teammates of a PR via email, so anybody could still potentially comment on the change if they find it objectionable

4. the sneaky commit

when do I use it?

  • after the code has been reviewed and merged into master
  • I need to make a small change (eg a copy change or bugfix) that’s not even worth notifying others about

what I do

  • just push the new commit to master.

5. the roger roger comment

when do I use it?

  • I’ve received actionable feedback from a code review on a branch
  • I’ve made fixes based on the feedback

what I do

  • I comment on the PR which includes the ref of the fixes commit
  • GitHub cleverly augments commit ref numbers with links to the diff, so that my colleagues:
    • are notified of my change via email
    • can easily click through to the commit diff
    • know that they can continue the code review

6. the creepin’ commit

when do I use it?

  • I discover that I’ve introduced small formatting bugs (eg unnecessary whitespace, missing newline at the end of file, etc), or
  • A logical code change really belongs in the previous commit, or
  • My code isn’t committable (eg some tests are failing) but I still would like to be able to roll back to this point, so I can experiment safely

what I do

  • in the first two cases, I amend the previous commit
  • for the third case, I have a work-in-progress (creeping) commit, which I progressively amend (or roll back to, if the experiment fails) until I reach a bonafide commit point

7. the forced branch

when do I use it?

  • I need to amend an remotely-pushed feature branch, eg I’ve explained something badly in a commit message

what I do

  • I amend the commit locally
  • I force-push the feature branch to the remote repo

While force-pushing to a remote branch is supposed to be a big git no-no, my experience is that there are rarely problems with this approach (as long as it’s only to the branch, and not to master). GitHub deals well with force-pushing to a PR branch, ie it doesn’t lose the comments on the previous commits, etc

8. the reformat peel-off

when do I use it?

  • I want to both change and reformat some code

what I do

  • I make a separate commit onto master, which contains only the reformat
  • I rebase my branch against master

This way, the diff on the branch with the change is much cleaner and more obvious for a code reviewer, because it doesn’t contain the reformatting

9. the prototype PR

when do I use it?

  • I want to get feedback on my ideas before implementing lots of code

what I do

  • I hack something together on a branch
  • I raise a PR for it, the intention of which isn’t to deliver finished code, but rather to be a starting point to discussion.
  • I close the PR (and kill the branch) when consensus has been reached on the next steps
  • I create another branch and PR, with proper code this time

I used to think that PRs were supposed to be raised when the code was finished. Now I have really grokked that “Pull requests are a great way to start a conversation” - GitHub’s functionality around PRs (such as inline commenting, replies, notifications and diffing) is excellent for facilitating code and design discussion, and can prevent developers going too far down dead-end paths.

Related posts