| Version 3 (modified by , 10 years ago) (diff) |
|---|
DETER Source Control Policy
DETER sources are managed under git with the authoritative copy on 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.
======================
Rework of the above ... GORAN
======================
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) This should be obsoleted by Release branches. It should be renamed to release 0.93.
DEVELOPMENT
This is the main trunk containing current development sources. It is integration and collection branch. No support will be provided for snapshots of this branch. Anybody installing deter software or doing development is expected to take snapshots of the latest Release branch. Development trunk will be at all times under OPS group control. No change can be committed into this branch prior to OPS group approval, completed documentation and prior testing.
RELEASE
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 a.k.a. MASTER.
A new Release Branch will be created as snapshot of a stable (tested) DEV trunk whenever OPS group decide to release new project(s), or periodically a number of bug fixes. This newly released branch will be then tested, updates may be applied to fix any problems. When finalized, changes will be merged back into DEV, and the new release will be announced. Problems within these branches will be fixed as minor revisions of the branch in question.
Release branches may periodically merged back into the Dev trunk, to pickup fixes done to that branch. The release branches will also be under OPS group control. We should support only one or two versions back from latest release. TBD.
Procedure for creating new release should be:
- take a snapshot of the dev branch, create new release branch
- Test and fix the new branch until satisfied
- Document, then push changes, if any back to dev,
- declare victory
PRIVAT
Developers may also create nonce branches to carry out development tasks, performance evaluations, or other common tasks. These branches are not supported by the OPS group. The only play ground for developers and partners (to carry out development tasks, performance evaluations, bug fixing or other) is inside these branches.
They are created and deleted as required with an assigned owner. Only the owner (or member of the owner's team) of such branch can commit to it.
Committing changes from ISI owned branches back to the Dev Trunk can only be done by prior OPS group approval, after all paper work detailing changes and testing performed is completed. Committing changes from NON-ISI owned branches back to the Dev Trunk can only be done ISI team, upon request ,after detailed review and after OPS group approval.
Procedure to prepare these branches for checkin should be
- pull all changes from DEV branch
- retest and fix
- Do the documentation, then create request to checkin into dev
- If ISI branch push the changes to dev, if not then OPS group will handle ...
Keeping track of fixes and features in various branches
A better release control will have to be created to track what was fixed in each of the branches. As a bare minimum fixes would need to be tracked against release versions along with what and how they were tested.
Again, we should only support few branches and obsolete older ones.
Definition of "accepted" change or satisfactory testing'
This is the criteria to declare a successful fix, new release readiness or project completion. Required to be satisfied before checking into DEV branch can be allowed. Need to define a default, minimum or required test hardware and/or procedure. A separate mini deter hardware setup will be installed at ISI to provide for testing. How would partners do that ? Suggestions?
Tagging:
Every major and/or minor release will be tagged in the DEV branch.
The major/minor number will be a part of each version of the released software.
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.
