Github Flow is a methodology and workflow that helps teams of developers use Git more efficiently. Github Flow uses the idea of Git branches to organize code in different states of development.

There are a bunch of different ways to use Git out there, and if we're not careful, everyone ends up using Git differently. If this is the case, we lose track of feature development progress, of graduated students' contributions, and of the most up-to-date version of the codebase. To avoid this chaos, we use a very specific system to organize Git.

If you are reading this, I assume you have a good sense of how to use Git and Github. More specifically, you should understand Pull Requests, Git in the terminal, and the theory behind Git in general.

Git relies heavily on the concept of branches of the codebase when making changes to code. Branches allow people to create diversions from the main codebase to change the program without changing the code that already exists.

In Robocup, development never progresses in a linear fashion. Rather, we all work independently and merge our code back together when it needs to be integrated into the code that gets run on a robot. Github Flow is a model that mimics this method of working. Every development to the codebase is created from a new branch; when development on these features is completed, these branches are merged back into the main branch that holds code that is loaded on the robot.

This system provides two general benefits: first, it separates feature development from the person working on the feature; second, it ensures that developers are always working with the most recent version of the codebase. As I write this, development happens on individual developers' forks of the main northern-bites/nbites repository. Today, if I were to develop a new feature, I would create a branch off my own repository, littleguy230/nbites, and develop from there. Github Flow allows me to create a new branch directly off of northern-bites/nbites. Development of that feature is no longer tied to my account. All development happens in a single repository, and there is once single location that holds the most recent version of the code.

The northern-bites/nbites repository will hold all the branches for Robocup development; everyone will push to and pull from this repository during development. There will be two branches on the repository that hold stable, recent code: master and develop. When developing a new feature, developers will create a new branch in northern-bites/nbites off of the develop branch, called a feature branch. Developers will commit new code to that specific feature branch, pulling from the develop branch constantly to make sure the feature branch stays up to date with the latest version of the codebase. When a feature branch is completed and tested, it will be merged with develop via a pull request, and that branch will be archived.

This system requires a branch naming scheme. This scheme is summarized in the table below, and expanded on below that. Note: All text should be in lower case, and words should be hyphen-delimited instead of underscore_delimited or inCamelCase or in any other word separation schema you can think of.

Branch	Naming Style	Description
Master	master	The most stable up-to-date version of the code base.
Develop	develop	The most recent stable version of the code base.
Feature	Any hyphen-delineated text	Any active development, organized by feature
Game	game-<type>-<date>	Any code that groups features together for a specific game or scrimmage. Used for competition.
Robotics Class	rob-<prefix>-<description>	Any code written for the Robotics class in Fall 2016
Other	o-<text>	Any other branch that does not fit into the first groups

The Master branch holds the most stable, up-to-date version of the code base. The code on this branch will always compile and be as bug-free as possible (however, it should not be updated with bug fixes). It should not have many new features added to it. The code should be playable with some version of the Robocup SPL rules, hopefully the current year's or the previous year's rules. Only the develop branch should merge into the master branch, and this should happen around once or twice each year when the teams determine it should happen. The master branch will rarely be used; however, it will be useful for demonstrations where the team needs to know it will all work as expected.

Code in the Develop branch represents the most recent stable developments of the Northern Bites. Like the master branch, it should compile, load on a robot, and be playable. Barring major, unsolved bugs, the code should not crash. This branch is the canonical most-up-to-date version of the code. Feature branches should always branch off of the develop branch, and should merge back into the develop branch when completed.

All active development happens in a feature branch. Generally, one person will take control of a feature branch, but if that person needs help, multiple people can work on one feature branch simultaneously. Feature branches should pull from develop regularly. Code from one feature branch should not depend on code from another feature branch; in other words, we should not be merging from one feature branch into another¹. Once a feature branch is deemed complete, it should pull from develop one final time, then a pull request should be submitted to merge the feature into master. That pull request will be reviewed by a jury of peers, and once it is deemed ready for prime-time, it will be merged into the develop branch and will become a part of Robocup history.

All merge conflicts should be dealt with in feature branches, rather than the develop branch. Every feature branch should be able to merge into develop with no issues. This can only happen if feature branches pull from develop often. This is critically important before the pull request is submitted. Github should give you a big green checkmark if the feature branch is able to merge into the develop branch. This green checkmark is pretty mandatory. It will definitely appear if you've pulled in develop and resolved all merge conflicts. I don't think I can stress this enough.

Feature branch names can be optionally prefixed based on which component of the code we're working on. The current list of branch prefixes is:

• be-: Behaviors
• com-: Communication
• loc-: Localization
• mo-: Motion
• tool-: NBTool
• ut-: Util / Admin stuff
• vis-: Vision

You can invent a new prefix if you want to (and if it's going to be helpful). If you do, add it to the list.

Development during tournaments or other events is pretty scattered, and sometimes can be a hastily jumbled mix of features and hotfixes that should be put on the robots, but shouldn't make it into the development branch. There are two types of games that would warrant a game branch: scrimmages, which are practice games that we do in the lab, and matches, which are actual games in tournaments that we need to quickly prepare for.

Every time we play, we should make a game branch, named for the game type and date. For example, a branch for a scrimmage on May 30th, 2016 would be named game-scrimmage-2016-5-30, using ISO date formatting because ISO date formatting is objectively the best. (A match in Germany on July 2, 2016 can be named game-germany-2016-7-2 if we want to denote for which competitions branches are created.) These game branches should be based off develop or other game branches, and can also include a bunch of uncompleted features or singular commits for hotfixes that should warrant its own feature branch to be merged into develop that way. Hotfixes could also get their own Github issue, if we really wanted to do it right.

Game branches are a dead end for code. They don't get merged into develop or anywhere else; after they've been used in a game, they shouldn't really be updated. If we make hotfix changes for a game, we can make a new feature branch like 2016-us-open-hotfixes that gets merged into develop the right way, or we can ignore those hotfixes and begin work on actually solving the bugs we find.

TBH, I haven't really thought of any circumstances where other branches would be useful. But given the nature of Robocup, I'm almost certain the team will find some reason that we need to make a branch in the northern-bites repository that doesn't fit into one of the categories above. If you need to make a branch that doesn't fit into any of the categories described above, prefix it with o- so we know it's not a feature branch.

• Git Flow, the predecessor of Github Flow
• Github Flow, a response to Git Flow and the basis for our Github workflow
• A lighter introduction to Github Flow, written by the folks at Github
• An external article describing the theory of different Git workflows

---

¹: If you feel like you need to merge a feature branch into another feature branch, think about what each feature branch represents. Are these two features that you are trying to test against each other? Maybe try finishing one feature first, merging that feature into develop, and getting the second feature to work with the new develop branch. Maybe the two features should really be one feature branch, in which case merging the two feature branches is actually totally okay as long as you delete the other one and stop all work on it. Maybe you are trying to consolidate features so that you can scrimmage? Use a scrimmage branch instead, which should be where you are merging not-yet-completed features together anyway.