Documents/OpenRadarRevisionControlUsage

Revision Control System Usage

Currently the standard revision control system for the Open Radar initiative is Subversion. The revision control archive is available online using [ ViewVC] and is located [ here]. Information on the usage of Subversion is available in the following links :

• Fast overview : subversion tutorial

• Overview of commands and usage : overview

• Merging and branching : svn branching and merging

• Archive structure : svn archive structure

• Software releases : releasing software with svn

• Bug fixing : bug fixing with svn

• official manual : svn book

The structure and use of the revision control archive is important. We structure the archive by general category and project. The current organization looks like :

documents/
projects/
        hardware/
                systems/
                subsystems/
        firmware/
                systems/
                subsystems/
                cores/
        software/
                infrastructure/
                radio_science/
                software_radio/
                software_radar/
        instruments/
                isis_array/
                beacon_receiver/
specifications/
standards/

This provides a more tree like structure than a simple organization by project. Within a given project we adopt the traditional subversion organizational structure which consists of a trunk, branches, and tags. In addition to this we add a releases directory which is used for formal releases. So the structure looks like :

•      /OpenRadarSVN/
       /OpenRadarSVN/category
       /OpenRadarSVN/category/project
       /OpenRadarSVN/category/project/trunk
       /OpenRadarSVN/category/project/branches
       /OpenRadarSVN/category/project/tags
       /OpenRadarSVN/category/project/releases
   

Within a given project the organization will be somewhat project specific. A recommended structure is as follows :

•     /trunk                 -- primary development trunk for planned and approved changes.
      /trunk/documents       -- documentation of the project 
      /trunk/documents/man   -- man pages of the software
      /trunk/documents/api   -- autogenerated API documentation of software and modules
      /trunk/documents/www   -- specific web page based documentation
      /trunk/build           -- directory for build specific code for the whole project
      /trunk/src             -- primary source code for the software or library implementation
      /trunk/src/modules     -- modules specific to this project and organized within a single project or library
      /trunk/src/examples    -- examples of using the software and modules
      /trunk/src/config      -- baseline configuration files necessary to operate examples and test
      /trunk/src/unit_tests  -- unit testing software to validate releases
      /trunk/src/tools       -- secondary software tools and scripts
      /trunk/src/www         -- web templates and data for the project (e.g. style sheets)
      /trunk/src/gui         -- graphical user interfaces associated with the project
      /trunk/src/www_ui      -- web based user interfaces associated with the project
      /trunk/INSTALL         -- Installation instructions
      /trunk/REQUIREMENTS    -- Requirements for the installation of this software (i.e. O/S, libraries, modules, tools, build environment, etc.)
      /trunk/README          -- Overview of the software, general installation, simple use, and notes.
      /trunk/LICENSE         -- License associated with the project 
      /turnk/RELEASES        -- Software release information and major changes
      /trunk/setup.py        -- python setup script (using distutils or just a script to automate the install)
   

The above structure is a general guide and will have variations for particular projects. Branches, tags, and releases are copies of the trunk structure for specific purposes. Typical usage is described in the links and notes above. Naming convention generally uses lower case with underscores (except where emphasis is required). In general python is used for high level installation control. This is true even if underneath the software uses GNU autoconf and configure.

There are two primary uses of the Open Radar SVN archive. The first is to host projects where the primary development is distributed and conducted directly using the archive. The second is for mirroring of releases developed by other projects and mirrored over using svnsync which provides one way replication. These mirrored releases will often be used as baseline software for dedicated OpenRadar projects.