Useful GitHub patterns

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.

18 comments

  1. What I would really like GitHub is to be able to create anew (as yet unchanged branch) and start a pull request immediately. Then in the pull request description describe what should be done on the pull request (including todo tasks). Then assign it to a colleague. It would be a much faster and more elegant way to assign task and start discussions. It feeds into your idea about using PR’s as a discussion point, I would just like to start with the discussion and then follow with the code.

    1. You can do that to some extent by starting with an Issue and turning it into a Pull Request after someone writes code for it. However, I’m not sure if any users other than the issue creator can have permission to attach commits to an issue.

  2. markduffy · ·

    On pattern one, why do you merge and rebase?

    1. Jake Benilov · ·

      Even if there aren’t any merge conflicts, the merge might introduce a logical problem, so I rebase in order to run the tests locally first.

  3. […] 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…  […]

  4. […] Jake Benilov   翻译: deepfish 译文链接: […]

  5. […] Jake Benilov   翻译: 伯乐在线 – deepfish 译文链接: […]

  6. […] Une présentation de certains scénarios d’utilisation de Github ou de git en général pour l…. […]

  7. […] 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.1. the peel-off PR2. the optimistic branch3. the heads-up PR4. the sneaky commit5. the roger roger comment6. the creepin’ commit7. the forced branch8. the reformat peel-off9. the prototype PR  […]

  8. […] blog.quickpeople.co.uk […]

  9. saddeveloper · ·

    Like the article. I’m looking for a bit of advice. I have a repo with a corrupt file (doesnt actually exist in any copy of the repo). Its stopping me repacking. The object has apparently long passed its sell by date. The un- repackable ropos have been cloned and used without other issues appearing in the code.Without loosing too much history, any advice on removing this orpaphed file referece from the repo?

    1. Jake Benilov · ·

      Hi Ian,
      I’m afraid I don’t really know the answer to your question – I’d resort to what you’ve probably done already, which is try to Google for it.

      1. saddeveloper · ·

        Ok thanks for replying, its probably ou there but I havn’t hit the correct phrase yet.

  10. This is great. Quite funny remembering how how I do things.

  11. […] Useful GitHub patterns by Jake Benilov […]

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: