Describe branches

diff --git a/branches.mdwn b/branches.mdwn
new file mode 100644 (file)
index 0000000..36734fe
--- /dev/null
+++ b/branches.mdwn
@@ -0,0 +1,57 @@
+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 also has a number of submodules. These include
+libradsec, Shibboleth, and libeap.
+Each commit to the main 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.
+
+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. See [[submodules]] for information on what
+to do if you need to work with one of these subprojects.
+
+## 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.
+
+## meeting/moonshot2 ##
+
+This is a [[integration branch]] for the second moonshot meeting. As the
+meeting approaches it is desirable to slow down the pace of change in
+code that participants will be using. It would be unfortunate to get
+into a situation where a change breaking master disrupted the
+meeting. This branch is managed by Sam Hartman; ask before committing to
+this branch.
+
+Participants at the second moonshot meeting are likely to find a build
+of this branch helpful.
+However during the meeting we will likely update this branch or
+sometimes work from master once we get basic functionality working.
+
+## tlv-mic ##
+
+This branch is a [[feature branch]] under development. The intent is to
+add a cryptographic checksum to Moonshot exchanges as part of
+extensibility.

diff --git a/index.mdwn b/index.mdwn
index 6f99a2a..68388a4 100644 (file)
--- a/index.mdwn
+++ b/index.mdwn
@@ -6,3 +6,4 @@ This is a wiki for those working on or using the Moonshot code base.
 * [[Prepare]] to use the system once built
 * [[Design]] Discussions
 * Information on [[VM Images|vmdk]]
+* Active [[branches]] of development