= DETER Source Control Policy =

DETER sources are managed under git with the authoritative copy on [https://github.com/deter-project/testbed github.] This document describes the structure of the repository and the policy for committing changes to the branches of that repository.

== The Branches ==

There are several distinguished branches of the DETER repository.  These include:

 Master::
  The most recent official stable DETER sources.  ''(A link to the most recent release branch??? What is the semantics of this branch now??? -- tvf)''

 Development::
  Current development sources.  These include vetted research extensions and runnable DETER sources. This branch has been reviewed by the operations group and run in the full ISI DETERLab environment for at least 1 week.

 Release Branches::
  A released version, known to be a valid starting point for collaborators.  Release versions are only updated to fix urgent bugs or security problems, reviewed by the operations group. These are labelled by version number.  The current Release is 0.93.

 Nonce Branches::
  Developers may also create nonce branches to carry out development tasks, performance evaluations, or other common tasks.  The criteria for commits to these branches are fluid, and the branches themselves are not guaranteed to be stable in any way.

== Rationale ==

The criterion that code in the '''development''' branch must run in the full ISI environment for a week is based on the premise that the development code is both the most technically advanced and has been seasoned in a harsh environment.  This is not a guarantee that the code is suitable for collaborators to use directly.  Code in the '''development''' branch is mature and seasoned, but may not be fully documented or may implement research features that collaborators do not want.

The operations group vets code in nonce branches through code review and testing in various test environments before installing it on the main DETERLab.  All code must go through a review, though sometimes a fairly informal one, before being placed on the production testbed for its one week trial.  After the one week trial has been completed successfully without incident, the changes are committed from the nonce branch to the '''development''' branch.

Collaborators are welcome to ask that their changes from a nonce branch undergo similar review and test.  Collaborator changes that pass the 1 week trial can be included in '''development''' at the discretion of the operations group.

This testing regimen implies that the code in '''development''' may lag the code running in DETERLab itself.  The intent is that DETERLab staff can always restore a safe, though advanced, environment from source control at any time.

Collaborators are welcome to track '''development''' if the are willing to tolerate the volatility of a research laboratory.  More conservative collaborators will track a released version.  The operations group will announce updates to released versions, as well as providing 3 month notice of ceasing support for a released version.  These announcements are news items on the DETERLab.