June 30, 2015
When you’re a solo developer, you can use Git in nearly any darn way you choose. No branching? Ok. Branch on everything? Sure. Want all your commit messages to consist of “stuff”? Knock yourself out. You might regret some of that in the long run, but it’s not hassling anyone else. But, as soon as you add another person into the mix, things will have to change.
One gigantic benefit from collaboration is having a second set of eyes look at your code. GitHub makes this easy if you follow a few steps.
[ed: This might be old hat for some of you, but I don’t know if I’ve ever read an entire guide for this, so I’m writing it all down. Please send me feedback, nicely, if there’s a problem.]
This one is optional, but does help in a few ways. The Organization becomes the face of any projects underneath it. It also makes a few things a little easier with regard to deployments, issue tracking, and documentation.
If the repository is called
some-org/project-x, then each developer forks that to create
sally-developer/project-x, and so on. If a repository is private on the Organization, your forks will be private too, and won’t count against your own private project count.
Now get your local copy.
git clone https://github.com/swilliams/project-x.git
Your fork on GitHub will automatically be your
origin remote. Add a remote for the Organizations repository. By convention this is typically called
git remote add upstream https://github.com/some-org/project-x.git
Working on a feature? Create a branch
feature-abc. Fixing a bug? Create a branch
git checkout -b feature-abc
Done with a feature or an issue? Push it back up to
origin (your fork).
git push origin feature-abc (you can add a
-u flag too to track the remote branch too)
Why do we go to the hassle of creating all those branches? Because with branches, you can create multiple outstanding Pull Requests at once. If you did all your development in
master, any additional commits you push up will be added to an open Pull Request, which can cause issues.
Multiple small Pull Requests are much easier to review. Would you rather review 3 files over 5 commits or 50 files and 75 commits?
Perhaps my favorite piece of functionality in GitHub is the Pull Request review process. Use it to annotate code and discuss. Merge it in if everything is good.
upstream. Upstream should only be updated through Pull Requests. Exception: pushing tags.
upstream regularly. The more codebases diverge, the more likely a nasty merge problem will occur.
Written by Scott Williams who lives and works in sunny Phoenix, AZ. Twitter is also a place.