branches.mdwn

   1 In order to help developers understand what branch they should be using
   2 here's a description of active branches in Moonshot.
   3
   4 ## Switching Branches ##
   5
   6 As with any Git project, you use the 'git checkout' command to switch
   7 branches. This might look like:
   8
   9     git checkout -b master origin/master #create local copy of master
  10     git checkout origin/feature # check out with no plan to commit
  11
  12 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
  13 libradsec, Shibboleth, and the moonshot GSS-API mechanism itself.
  14 Each commit to the master Moonshot repository includes a reference to the
  15 appropriate commit of a sub project to use. This is a *commit*, not a
  16 *branch*. That is, a Moonshot developer needs to make a explicit
  17 decision to update what version of a subproject is being used on a given
  18 moonshot branch.  A commit of the master repository describes all the Moonshot software in use including every version of the submodules.
  19
  20 However, git does not automatically adjust the version of subprojects
  21 you have checked out. After updating, either by pulling, checking out a new branch, merging or
  22 rebasing, it is a good idea to run 'git submodule update'. This command
  23 will set every subproject to the expected commit stored in the Moonshot
  24 branch you have checked out.
  25
  26 ## Master ##
  27
  28 The master branch is intended to be stable but active. Code on the
  29 master branch is expected to build and work; if it does not, please
  30 notify the mailing list. However, the master branch is also the target
  31 of frequent integrations. When code is mature enough that it should
  32 generally be used by other Moonshot developers, it should be merged to
  33 master.
  34
  35 At least until we have stable releases, new users should be directed to
  36 master.
  37
  38 [[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.
  39
  40 The Ubuntu automated builds merge the changes from master together with the changes from the Debian branch below to generate packaging.
  41
  42 ## Debian
  43
  44 The Debian branch includes [[Debian packaging|release/debian]] which is used for Debian and Ubuntu builds.
  45
  46
  47 # Working with Submodules
  48
  49 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.
  50
  51 In all cases, we're using the debian branch for debian packaging.
  52
  53 ## When you have something worth saving.
  54
  55 If you have something working well enough to include in the master repository then:
  56
  57 1. commit to the subproject
  58
  59 2. push the branch containing the commit in the submodule.
  60
  61 3. Run "git log origin/branchname" in the submodule and make sure your commit is there
  62 4. Run "git add submodule_directory" in the master repostiory
  63
  64 4. Commit the master repository
  65
  66 5. Push the branch in the master repository