In order to help developers understand what branch they should be using
here's a description of active branches in Moonshot.

## Switching Branches ##

As with any Git project, you use the 'git checkout' command to switch
branches. This might look like:

    git checkout -b master origin/master #create local copy of master
    git checkout origin/feature # check out with no plan to commit

However, Moonshot's source is distributed as a master repository  with  a number of [submodules](http://git-scm.com/book/en/Git-Tools-Submodules). These include
libradsec, Shibboleth, and the moonshot GSS-API mechanism itself.
Each commit to the master Moonshot repository includes a reference to the
appropriate commit of a sub project to use. This is a *commit*, not a
*branch*. That is, a Moonshot developer needs to make a explicit
decision to update what version of a subproject is being used on a given
moonshot branch.  A commit of the master repository describes all the Moonshot software in use including every version of the submodules.

However, git does not automatically adjust the version of subprojects
you have checked out. After updating, either by pulling, checking out a new branch, merging or
rebasing, it is a good idea to run 'git submodule update'. This command
will set every subproject to the expected commit stored in the Moonshot
branch you have checked out. 

## Master ##

The master branch is intended to be stable but active. Code on the
master branch is expected to build and work; if it does not, please
notify the mailing list. However, the master branch is also the target
of frequent integrations. When code is mature enough that it should
generally be used by other Moonshot developers, it should be merged to
master.

At least until we have stable releases, new users should be directed to
master.

[[Centos packaging|release/centos]] is built directly from the master branch.  However, while master is always built on Centos, the version numbers of Centos packages need to be incremented before new Centos packages are installed.

The Ubuntu automated builds merge the changes from master together with the changes from the Debian branch below to generate packaging.

## Debian

The Debian branch includes [[Debian packaging|release/debian]] which is used for Debian and Ubuntu builds.


# Working with Submodules

Whenever you run "git submodule update", all submodules end up in a [detached head](http://eclipsesource.com/blogs/2011/05/29/life-lesson-be-mindful-of-a-detached-head/) state.  This produces very confusing behavior if you commit changes.  It's easy to lose track of changes.  Prior to changing a submodule, check out a branch.  Typically the same branch as the master repository, although for projects imported from other sources we often use the moonshot branch for our local change.  As of early 2014,, we're using the tr-integ branch for freeradius.

In all cases, we're using the debian branch for debian packaging.

## When you have something worth saving.

If you have something working well enough to include in the master repository then:

1. commit to the subproject

2. push the branch containing the commit in the submodule.

3. Run "git log origin/branchname" in the submodule and make sure your commit is there
4. Run "git add submodule_directory" in the master repostiory

4. Commit the master repository

5. Push the branch in the master repository