GitHub.com flow |

This content originally appeared on @mdo and was authored by Mark Otto

The term GitHub flow refers to how one can develop software with GitHub. It’s a process that minimizes friction, enables asynchronous communication (and development), and is decently flexible. For an overview, read Understanding the GitHub Flow on GitHub Guides.

Applying the GitHub flow to development of GitHub.com The Website™ builds on that, and tends to go something like this.

1. Find something to work on

Issues on the github/github repository are the easiest way to find things to do. Anyone can open them, and anyone can comment on them. User and team at mentions are available for pinging folks with bugs, feedback, or questions.

It’s worth mentioning though that we sometimes jump right into code from a meatspace discussion or from a tweet. Twitter is the best way to find out if we have bugs or performance problems in real-time while deploying code.

Bottom line? Get to writing code as soon as possible.

2. Branching

At GitHub, almost every new contribution happens in a branch. What’s in master should always be stable, passing tests, and ready to deploy in an instant. When I figure out what I’m working on, I cut a branch from master and get to work.

My branch naming scheme is sometimes serious and relevant, and usually not useful in the slightest. sidebar_hit_areas and today_we_celebrate_our_independence_day are both branch names that I’ve recently worked on. Both are long gone though.

Great branches really should include accurate names, but most of the time it doesn’t matter because they’re so short lived. Plus, snagging the name of a branch is as easy as copy-pasting from the top of a pull request.

Bottom line? Just cut a branch and write some code.

Not every change happens in a branch. Super small changes can be made right to master should the occasion, or emergency, call for it.

3. Pull requests

Branches are ephemeral. They exist for the sole purpose of creating a pull request. Pull requests are more important than branches for a number of reasons:

Suggested changes are (justifiably so) more likely to be shipped if there’s an available pull request for it.
Branches get deleted, and thus code can be lost. Pull requests are never deleted, only closed or merged.
Pull requests, like issues, are search-able, label-able, milestone-able, and mention-able. Branches? Not so much.
Pull requests can be discussed in the open and linked to.

Pull requests should be created as soon as possible. You should push your code and open a pull request when:

You have changes that are completely finished and just need review before merging.
You have a bunch of things to do and need to use GitHub task lists to outline what’s left.
You have questions and have no idea how to finish a part of your intended changes without pinging coworkers.
You have an idea that you’d like to discuss and test, but might not ever intend to ship.

As a side note, the GitHub.com code base has 50% more pull requests than issues:

For those who asked, to date, the github/github repo has ~10,000 issues and ~15,000 pull requests.
— Mark Otto (@mdo) April 29, 2014

Bottom line? Pull requests are cheap and effective. Create them early and often.

4. Discuss your code

You can define a pull request a few different ways, but first and foremost it’s a discussion around code. Code review. The best code reviews (and thus, pull requests):

Have a limited set of changes
Specifically at mention individuals or teams
Include before and after screenshots, if dealing with visible front-end changes

There’s no harm in creating lots of pull requests for discussion. If you’re concerned about pushing unfinished work, let people know you’re not yet ready for feedback or merging to master. Two easy ways are to preface your pull request title with WIP: or to include a row of :construction: emoji in the opening comment.

Bottom line? Make it as easy as possible for your peers to help you ship your code.

5. Shipping it

When it comes to deploying or shipping your code for GitHub.com, you have a few options:

Branch deploy: deploying your branch temporarily to production in place of master.
Branch lab deploy: deploying your branch to a specific server, which when deployed, gives you a unique URL (e.g., hi_mom.branch.github.com).
Merging to master: merge your branch via the merge form on your pull request. Your branch is merged, tests are run, and master is redeployed with your changes to production.

The best thing to do is use branch lab because you get a real URL you can share with folks around the office. URLs are the best way to drop a link into Campfire to invite folks to view some changes. Also, there’s basically no limit to how many branches can be deployed on branch lab.

When you’re changes have shipped—meaning, they’ve been merged to master—you delete the branch. GitHub will automatically prompt you do to so after merging to ensure your list of branches stays lean.

Bottom line? When you’re ready to ship, test your changes in an isolated branch lab, then merge to master.

Shoutout to Hubot

Hubot is our Campfire bot that literally does (almost) all the things. Find Google images, remember things, run tests, and most importantly, deploy code. When I’m ready to deploy code, I just pop into Campfire and tell Hubot to get to it:

/deploy github/hi_mom to branch-lab

Hubot will automerge master if there are new changes not in my branch yet, run tests again, and then deploy my branch. If my tests fail or haven’t yet finished running, Hubot tells me that right in Campfire.