Git Policy

This page isn't intended to be an exercise in bureaucracy, but it is good to have some base policies that everyone should adhere to. All branches are listed in Branches. Please do your part to keep the page up to date.

Terminology

Some is general Git terminology, some is internal team usage.

• HEAD : the current branch and revision of your repository
• Origin / GitHub : the remote Git repository on GitHub
• Pushed up : having your changes (on whatever branch) up on Origin. Ex: "Have you pushed up the new parser stuff?"
• Pulling changes : getting someone else's changes and merging them into your branch,
• Merge : the best thing about Git.
• Fast-Forward : a special kind of merge where you merge with a branch that is directly upstream of HEAD. In this case, Git simply moves your branch pointer forward. These are the cleanest merges around.

Workflow

In general, the typical workflow should be as follows:

1. (If needed) checkout the branch you're working on:

• git checkout coolfeature
• grab the latest changes
• git fetch origin
• make sure your work branches are synched with the main branches
• git merge origin/development
• code, code, code...
• push up your work
• git push origin coolfeature

This seems a bit excessive, but is quite easy to follow. This cycle ensures that you never stray from the main branches. And the less you drift, the easier it is to stay up to date. Another advantage is that this makes it very easy for a maintainer to pull your changes into the main branches.

Branches

Basic Naming

All branches must adhere to this naming scheme — we will chase cases that break convention.

Branches should be named in lowercase with no spaces. Dash (-) is the preferred separator. The slash (/) can also be used to sort branches into folders.

Naming-wise, branches fall into one of two categories:

• "Bare" branches

  These are branches where their names are simple and unstructured. These are further subdivided into primary and feature branches. Please confer with other developers before creating bare branches.

• "Folder" branches

  These branch names have structure: the first part acts as a prefix to allow for grouping.

  • The personal branch prefixes, which are a person's initials followed by a / then some further descriptor.
  • Complex feature or sub-project branches, such as those for symphony.

  Note that you cannot create just the prefix: you actually have to create a branch like jwc/main that uses the prefix.

Branches in a personal folder may use any name after the prefix, however, please avoid transitions such as jwc/thing to jwc/thing/subthing as this will cause general annoyance. Git does not allow you to have a folder branch and a leaf branch with the same name, so the two branch names mentioned in the last sentence are mutually exclusive.

Primary Branches

This is the the main set of branches. These branches are fixed and used for daily builds, releases, etc. You should NOT commit work to these branches (except test). If you have interesting stuff you want pulled into a main branch, contact the owner and he will pull your changes.

Feature Branches

These branches track ongoing large projects. These branches should only exists as long as the feature is being actively developed. Afterwards, they are pulled into a main branch and deleted (remember to remove them from the table). Multiple people work on these branches so you should should make sure that you never push up work that breaks the build. It should always compile and pass all tests

User Branches

A user branch is the playground of its owner. There are no guarantees that a personal branch is stable or even compiling. We record them here only so we so that we know who to get in touch with. Guidelines:

1. Please do not abuse this by creating a dozen personal branches.

• Do not commit to or otherwise make changes to branches with someone else's prefix.
• Merge from development frequently.

Misc.

• Do NOT push up your tags
• Branching is great! Branch as often as you want and need.
• Once you are done with a branch, delete it!
• Git has a local repository. Take advantage of this by committing frequently. Multiple small commits are easier for others to work with than a single big one.
• Watch out for line endings! Try to avoid committing files with CRLF terminators. In theory, this should be taken care of automatically by our Git settings but it pops up occasionally .
• Once a personal branch is no longer being used for anything, delete it on the remote.
• Once a feature branch is no longer being used for anything, contact the release manger so he can coordinate its removal.
• Be sure to configure your git installation with a name and email so your commits are properly identified.
• The repository history is public. Keep your messages and branch names civil.
• Write meaningful commit messages. "changed method X" is not a meaningful message. Anything that is obvious from the commit diff is not a meaningful message.
• If your commit fixes an issue, reference the issue in the commit with #[issue number]
• Remember, commits are local. You need to push up your changes for the rest of us to have access to them.