A Georgia Tech gitflow Process

Category

A proposed workflow for how smaller teams can code collaboratively with git at Georgia Tech.

Defining Git

Git is an environment-agnostic version control system that allows teams or individuals to collaborate on projects in a distributed fashion. Git was created for the command line, but there are also GUI clients available.

Commits

Under the hood, git is powered by a tree of commits. Each commit tracks the difference between it and the previous commit in the tree. This saves tremendous space by storing only the changes and not the entire changed file.

Repositories

Repositories (repos) are a place where files and their histories are stored. Local repos are stored on your machine and/or the production server. The remote (origin) repo is an agreed-upon authoritative repository through which all changes flow. We use the GitHub.gatech.edu enterprise website to store our remote repos, as well as to manage their permissions and the code review process.

Branches

Central to git is the idea of branches. Each branch is just a pointer to a commit in a tree. So making a new branch is as cheap as initializing a pointer to the current commit, and updating that pointer (and only that pointer) when work is done on that branch. And because of the way git stores commits, storage for the work done on branches will be cheap too.

Branches are a way for collaborators to work together without all working on the same version of code. This allows for more advanced nonlinear workflow than a single stream of commits. It also allows for powerful administrative features such as code reviews, keeping the master (production) branch stable and testing new features without compromising that stability.

Pull requests

Pull requests are a GitHub-specific feature that encourages review of any code changes before they go live. It also gives administrators a chance to request changes or resolve conflicts before the final code is merged into the master branch.

Collaborative Workflow Overview

This workflow is based on the lightweight GitHub Flow system. This choice reflects our emphasis on less complexity for our small team, instead of focusing on a perfectly clean commit history.

In this system, all development (whether fixes or features) is done in branches and then merged back into the master/production branch when completed. Below is a sample timeline for the workflow of creating and implementing a new feature branch.

 

Visual diagram of 5-step Georgia Tech gitflow workflow

This workflow follows 5 rules:

  1. The master branch is protected and should be kept deployable to production at all times. This is the most important rule. All code merged into master should first be thoroughly tested and reviewed. It is possible to revert the master branch, but this should be avoided whenever possible. Even if a hotfix is needed, verification of the fix should always be done in a branch. This is especially essential when our server is configured to automatically pull updates from the remote origin repo, meaning that any commit to master will quickly be made live.

  2. Create separate branches off the latest master for each feature. Since branches are cheap, use one for every feature or fix. And, to ensure updated code, branch off of the current master.

  3. Before every commit, pull the latest master and merge it into your local branch. One of the most challenging tasks in collaborative git is updating an existing file that needs to integrate divergent code changes from multiple developers. Merging the latest master branch into your local feature branch before every commit will largely prevent that by ensuring that any discrepancies in code are limited in scope and easily resolvable.

  4. Constantly push all branches to the remote/origin repo. The remote repo isn’t just for maintaining the master branch: it can also store any other branches you are developing. This allows others to contribute to the individual branch you are working on (if you both are working on the same feature, for instance), as well as showing the current progress on each feature.

  5. Use pull requests to add completed features to the master branch. Pull requests allow new features to be vetted by administrators before being added to production. Once a feature is in a mergeable state, a pull request allows discussion, review, and finally approval to get integrated into our live, master branch.

(Credit to Eli Trexler for putting together a lot of this content).