Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

@brandly
Last active January 3, 2016 12:19
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save brandly/00fe9e1981a41a68708f to your computer and use it in GitHub Desktop.
Save brandly/00fe9e1981a41a68708f to your computer and use it in GitHub Desktop.
thoughts on branching and pull requests

here's how i think of branching.

purpose of branching

you need to write some code. since you may end up writing good code, but there's a chance you'll write bad code, branches allow you to freely commit your changes as you go along without affecting the core of the project. if you end up with something you don't like, you can clip the branch like nothing ever happened.

i think branches fall into a few categories.

bugs

someone has detailed a problem they've run into. you're here to fix it.

in some situations, the source of the problem is obvious. these bugs are typically fixed with ease.

some bugs, however, are more elusive. you may write some code thinking you know what the problem is, before realizing you're heading the wrong direction. just clip the branch and start fresh with your newly found insight.

features

you've decided something new needs to get added to the project. the new feature has been laid out in some detail, but, as you know, you end up deciding the more specific details as you write code. feature specs can only take you so far (and may change).

branches allow you and your team to play with and experience the new feature before anything is set in stone. details might get changed. the feature might even get dropped. but have no fear. no commits have touched the master branch.

ideas

one day, you're writing code and a great idea pops in your head. it might involve something new you don't know anything about. the details might be hazy. but you can still code and explore without any fear of causing damage.

this is the one type of programming that would rarely happen without a branching model, but i think it can be super useful.

tips & trix

occasionally, you write some code that might even solve the problem, but along the way, you get to know the problem more intimately and find yourself thinking, "hey, this solution might cause more problems further down the road" or, "wow, this could be solved in a more eloquent manner." in the moment, it might be hard to turn back, but technical debt is bad, and you'll ultimately save time for yourself -- or someone else working on the project -- if you choose to fix it while the problem is fresh in your mind. even if it doesn't seem like a big deal at the time, in 3 months, when the problem is back to bite you, you no longer remember all those little details you once discovered and refactoring becomes far more difficult.

purpose of pull requests

first and foremost, pull requests allow you to share your changes with other members on your team before they get merged in. a fresh set of eyes might catch a silly error you didn't notice or a deeply rooted problem that you didn't consider.

sharing a pull request

sometimes, a pull request is something minor and easy to digest. these probably don't need much description.

other times, you're introducing new functionality or changing the way something used to be implemented. in these situations, you should describe as much as possible what has been introduced and why you were motivated to make these changes. this allows others to review your code with a better understanding of your perspective, which makes for better code reviews and ultimately better code.

also, before submitting a pull request for other to view, you should look at all the files that have been changed first. often, you might find some logging that should be removed, extraneous vertical space, or other silly errors. take care of these before several other people read over your code.

reading a pull request

there are a handful of things i look for when reading someone's code.

pretty code

without changing functionality, could these few lines be written more cleanly or expressively? is there something in this language they're not taking advantage of and maybe don't know about?

sometimes, entire loops can be removed, but more often, small changes allow the code to more expressively describe what is taking place, which lets anyone in the future understand the code more easily and quickly. also, you're sharing your knowledge with the rest of the team, which should ultimately lead to better code written by all.

if your project has a style guide, now would be a good time to enforce guidelines.

external factors

the person who originally wrote the code was focused on a specific problem and had a lot to keep in their head while they were in the process of writing. with a fresh set of eyes, you might be able to recognize an indirect problem being introduced. try to think about how this new code fits into the big picture.

tips & trix

pull requests should be as focused as possible. minimize external effects.

ideally, branches get opened and merge in as little time as possible. try to understand what your true goal is when creating a branch. since someone else is probably making other changes to the code base, staying focused keeps your branch from drifting away from the rest of the code too far.

the ultimate goal of a pull request is communication within a team. do everything you can to support this goal.

resources

how to branch/merge

using pull requests

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment