The following is a slightly opinionated Git-based workflow that helps you to manage your project with a team without having to worry too much about the politics of code management. Thanks to Ka`a Kihe for writing it.
A Git MVP Workﬂow
Getting a product out, especially for demo purposes, can be both exciting and stressinducing. When dealing with a team where more than one area of your codebase is being
worked on at once, the complexity of code management is something you don’t want existing
as a big deal, especially under a time crunch.
The following is a slightly opinionated Git-based workflow that helps you to manage your
project with a team without having to worry too much about the politics of code
management. There are good reference posts like A Successful Git Branching Model (http://
nvie.com/posts/a-successful-git-branching-model/) and the Git Branching and Merging guide
(http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging). This will
incorporate ideas from that while trying to keep things simple and let you focus on your work.
Note that the following model does the following:
• relies somewhat on being comfortable with the people you work with (that means physical access
or, at least, direct chat access)
• ignores automated testing setups (though doesn’t discount them — test if you can!)
• assumes that you are using the GitHub for Mac client. You can still follow the branching model if
you’re familiar with Git on the command line.
We’ll start with a quick intro on actually getting everyone on Github and starting a project
NOTE: The following next couple of steps assumes that the project is being managed from a
personal account instead of Github Organizations.
GET EVERYONE ON GITHUB
Everyone on the team — designers, developers, business analysts, your barber, the mail man
— need to make sure they’re on Github. Get everyone’s Github names immediately, and email
it to everyone on the team in a list for reference.
For those that haven’t yet, make sure those on Github have their SSH keys added to their
accounts. Directions: https://help.github.com/articles/generating-ssh-keys
CREATE YOUR PROJECT
Come up with a name for your project to get started. Don’t worry, you can always change it
later. Invite everyone to the project as collaborators, which will allow them to contribute
directly to the project. Directions: https://help.github.com/articles/howdo-i-add-a-collaborator
It’s important to track and assign issues to everyone working on the
project so that everyone has direction on how to contribute — this is true
for everyone involved in the project, even non-developers. Using the
issues section of your code repository in Github will help to keep track of
everything that’s going on and assign issues to people.
We won’t go over how to use the issue tracker here (it’s really easy!), but
Github has a great writeup on it – https://github.com/blog/831issues-2-0-the-next-generation.
For every new feature, bug, requested change, everyone on the team should use the issue
tracker to input issues into the system. When inputting issues, make sure to assign someone
to the issue so that they know to take a look at it. If you’re not sure who the issue should be
assigned to, create the issue and speak to your team the next time there’s a status meet up.
Communication is a big factor in a successful team project. It’s good to have a general sense
of who currently “owns” what in the team. If one person is generally handling most of the
front-end issues, assign some of the HTML and CSS issues to that person so it’s easier to
prioritize or resource help if needed.
Download the GitHub Mac client — http://mac.github.com/. After installing and opening it,
walk through the setup, including signing in to your account. When complete, you should see
your account name on the left and all your Git repositories on the right. If the project is not yet
on computer, choose the project and choose “Clone to Computer”. After the project’s done
downloading, or if it’s already been downloaded, double-click it.
From here, you’ll be able to see everything about your project:
• History will show you all the changes that have been made to the project by
everyone on the team.
• Changes shows all the current changes that you’ve made to your code.
• Branches shows all the code branches you’ve made — refer to the branching
model in the next section.
• Settings allows you to configure the address of the repository and which files
you may want to ignore.
THE BRANCHING MODEL
Refine issues +
When you start a project, your code lives on the master branch. Keep this branch clean,
meaning don’t put unfinished or buggy pieces of code on there. The master branch is what
the public will see when code is released.
Right after the project is created, create a development branch. You can do this in GitHub for
Mac by going to the Branches section of your project, choosing a branch (in this case master)
and clicking the + button at the end of the branch description. Name the branch
From here, the team can create branches from the development branch to work on diﬀerent
features. The rule of thumb: if it’s a feature, issue, bug, or idea that you’re trying, branch it. As
much as possible, try not to commit directly to the development branch.
For example: if someone is working on adding a footer to the layout, create an issue for it in
GitHub — “Front-end layout - create footer.” Create a new branch from the development
branch and name it something similar. Even better, reference the issue number in the branch
name. (e.g. “create_footer-43”).
COMMITTING YOUR CODE
While you’re working on your code, make frequent commits to your code when you complete
either the entire issue you’re working on or parts of the issue you’re working on. Committing
broken code is frowned upon, so make sure what you’re committing doesn’t break the project
as much as possible.
The commits that you make should also stay in context to the issue you’re working on. If
you’re working on implementing a page footer, don’t include work on fixing issues with the
navigation bar if it’s irrelevant to working on the footer.
You can view all the changes you’ve made to your code in the Changes tab of your project.
Once you’re satisfied with your work and you want to commit, write a short description in the
Summary field (and a longer description if necessary in the Description field) and click
If you’re confident you’re finished with a feature, include “Fixed #(issue number)” somewhere
in the summary, preferably at the end. (e.g. “Implements the page footer. Fixes #23”). This will
automatically close the issue in GitHub. See more — https://help.github.com/articles/closing-
issues-via-commit-messages. When an issue is closed, whoever opened it will be notified. If
you were not the one who opened the issue, you may want to work with the person who
opened it to verify that the issue is addressed. The issue-opener may decide to re-open the
issue if the solution is needs additional attention.
Whenever you commit code, it stays on your computer until you sync your branch. Click the
button to Sync Branch in order to push your code up to the repository at GitHub.
PULL REQUESTS - GETTING YOUR CODE INTO THE
After you’re done committing your last piece of code for
your branch, head to the web interface for your project
at github.com. From the home screen of your project,
there’s a drop-down menu for branches. Choose the branch that you worked on, then click
the green button. This will create a pull request.
A pull request is a request to the team to look at the code you’ve done and test it out. If
everything looks fine, whoever has the authority to merge the code (this should be figured
out internally within the team) in can pull the code in to the original branch the code had
branched from. That is, if a feature branch called refactor had originated from the
development branch, then the code will be pulled in to the development branch.
After pulling the code in, there should be a button to delete the branch the code came from
(i.e. delete the refactor branch, in this case). Go ahead and delete the branch so that your
repository doesn’t fill with unneeded branches.
COME TOGETHER (OFTEN)
Set frequent internal milestones for merging in Pull Requests and testing the development
branch as often as possible. Every two or three days could do it, depending on the project and
the size of the team. This way, everyone can more or less stay on the same page.
If there is a feature branch that takes long to develop, but pull requests are being brought into
the development branch, be sure to merge the updated code from the development branch
often. You may run into conflicts, but this way you can fix your code in context of the most upto-date code work on the development branch. This will help to actively fix bugs and reduce
larger code conflicts.
When it is determined by the team that the development branch has a good number of
features, and that everything generally works, merge it into the master branch.
You can do this in GitHub for Mac by heading to the Branches tab and clicking Merge View.
Drag the branches into their positions with the branch that you want to merge into on the
right. When merging development into master, master would be on the right.
TEST, TEST, TEST
During the internal milestone period, make sure to test your project amongst the team and
continue to add new issues in GitHub as necessary.