next up previous contents
Next: 8 Shared and External Up: dev_guide Previous: 6 Coding Conventions   Contents


7 Configuration Management

It is recommended that all CCSM development teams develop code with the help of a robust software configuration management (SCM) tool, such as CVS. The goal is to establish, document, control, and track the evolution of source code and related documentation throughout the software life cycle.

7.1 CVS Repository Access

The CCSM Repository Access Policy web page describes in greater detail the current access policy and other issues.

To request access to the CCSM code repository for development, please see the CCSM Repository, Request for Access web page. This site contains details about how to request access and the current restrictions on access.

7.2 Procedures for the Central CCSM Repository

This section describes the specific procedures that apply to the central CCSM code repository and official releases of CCSM coupled models.

7.2.1 Commit Sequence

Currently NCAR's CSEG is using the configuration management tool CVS to manage all of the official CCSM projects. CVS works from a central repository with developers "checking out" a "sandbox" version of a standard release that they can experiment with. When developers have something useful they can then "commit" their changes to the central repository. Other developers get these changes by "updating" their checked out versions with "cvs update". This allows multiple developers to work on changes simultaneously, without having to stumble over file locks. If two developers change the same line of code CVS triggers a "conflict" and displays both versions in the file. The developer then has to pick how to resolve this conflict by hand. CVS also allows a complete configuration of a given project to be tagged with a single version name so that it can be reconstructed later.

CCSM will maintain one coherent repository of all CCSM model codes at NCAR. This repository will contain a module that enables checkout of the complete system (the coupler and all active and data models).

CVS online documentation

  1. Need for new version driven by global or component issues
    The need for a new version of the system will arise either because of project-wide issues or because of changes happening to individual components.

  2. CCSM liaison tests with last CCSM version
    The CCSM liaison tests the new component version with the CCSM model system and ensure it works.

  3. Liaison modifies build/run scripts
    The CCSM liaisons are responsible for maintaining the build/run scripts in the CCSM module (the "bld" and "scripts" directories). In general a component model liaison should only work with the scripts for the models they are responsible for. Anyone working with the other scripts should contact the other liaisons, so they know what each is working on. When any commits or tags to the "bld" or "scripts" modules are done the liaison should send mail to the "" e-mail group with a short description of the changes.
  4. Coordinator checks with each component
    The CCSM coordinator checks with the other component liaisons to see if their components need to be updated.
  5. CCSM quality assurance lead tests the system
    The CCSM quality assurance lead tests the entire system. If problems occur in a given component the liaison for that component is responsible for implementing a solution.
  6. CCSM coordinator tags the new version
    The CCSM coordinator tags the complete CCSM model system.
  7. Change Logs documented during tag
    During the tagging procedure the new version is documented and the CCSM web-page automatically updated. Also e-mail is sent out to the "" e-mail group.
  8. New versions checked out to /fs/cgd/csm/collections
    The CCSM coordinator then checks out the new CCSM version to /fs/cgd/csm/collections. The version is checked out with the same directory name as the tag-name. For example, if the tag-name is "ccsm1_5_1" then the version under collections will be checked out as:
          cd /fs/cgd/csm/collections
          cvs co -d ccsm1\_5\_1 -r ccsm1\_5\_1 ccsm1

7.2.2 How to Commit

All access to the CCSM repository is via goldhill. Either run CVS directly on goldhill or via:

The later allows a user to access the repository on the CVS server on goldhill while logged into another machine.

CVSUMASK and CVSROOT must be set properly before check-in.

setenv CVSROOT /fs/cgd/csm/models/CVS.REPOS
setenv CVSUMASK 002

Also set CVSEDITOR if you want to use a different editor when entering your commit log. This editor will also be used when editing the ChangeLog rather than the default X11 widgets (for the modules that manage Change-files).

7.2.3 Useful Modules

To list all modules: cvs co -c:

Module Description
CVS.SCRIPTS Scripts for managing the CCSM projects. Miscellaneous tasks such as checking authorization lists, and automatic editing of ChangeLogs when a tag is initiated. (Note: open only to the "cgdcvsadmin" UNIX sub-group, which should be the same as "ccsm-reps")
dev_guide CCSM Developers Guide (this document).
bld CCSM Makefiles.
ccsm2 The complete CCSM version 1 project. Contains all official CCSM models, run scripts and Makefiles.
csm_share The module of code shared between CCSM components.
makdep Dependency generator.
scripts CCSM run scripts.
versions ChangeLogs for CCSM and several major CCSM component models.
ccm Community Climate Model. This module also contains the active land surface model "LSM" and "CLM2". Directory structure is modified from "ccsm2". Several submodules also exist.
lsm Active Land Surface Model version 1.
lsm2 Active Land Surface Model version 2.
clm2 Community Land Model version 2.
ccm3lsm_doc Users-Guide documentation for the CCM and LSM.
ccm_unit_testers Unit-testers for ccm source code.
cpl5 Coupler.
csim4aio Community Ice Model and Active Ice model. This module also contains the coupler and necessary data models to run the stand-alone ice model. Directory structure modified from "ccsm2".
dice5 Data ice model.
dlnd5 Data land model.
docn5 Data ocean model.
latm "Large" (as in Bill Large) data atmospheric model. Used for running with observational atmospheric datasets rather than model (ie. ccm) datasets.
pop Parallel Ocean Model. Active Ocean model. Several submodules also exist.
timing General set of timing utilities.
pilgrim A generalized set of parallel-decomposition utilities.

7.2.4 Management of Change Logs

The following modules maintain a set of Change-files: ccsm2, ccm, pop, and csim4aio. In the simplest case there are two files: a ChangeSum and a ChangeLog. These are both kept in the repository for the given component and are accessible from the web. The ChangeSum gives a short one-line synopsis of changes between the current tag and the previous one, while the ChangeLog gives a more detailed description. Some projects also maintain a BranchSum and BranchLog that gives a short or log description of branch tags. These files are maintained outside the repository, but are also web-accessible. POP maintains a LANL_ChangeSum and LANL_ChangeLog kept in the repository to track the changes in LANL versions of POP.

The modules that maintain ChangeLogs use a set of scripts to help make this process easier. These scripts are automatically invoked when a "cvs tag" is invoked. On machines with Perl-Tk installed X11 widgets are used to answer relevant questions. The Change-files are brought up as templates in a simple editor. If the user wants to use a different editor for the Change-files they need to set the CVSEDITOR environment variable to their selected editor.

7.2.5 Naming Conventions

Major new versions of the CCSM are designated CCSM1.0, CCSM2.0, ... . Significantly new developmental versions are designated CCSM1.1, CCSM1.2, ... . Incremental development versions of the CCSM are designated CCSM2.0-beta01, CCSM2.0-beta02 ... . Development versions represent incremental improvements and developments on the system.

Module Tag Branch Tag Frozen Branch Tag
bld bld_[a-b]YYMMDD
ex. bld_a001017
None None
Note: Only ``ccsm-reps'' can commit changes here.
ccm ccm#_#_#
ex. ccm1_10
ex. ccm1_10_brnch_bug_fix
ex. ccm1_10_brnchT_bug_fix1
Note: Branches are used extensively and branch names are tracked in a BranchLog. Frozen releases along branch developments are tracked also in a BranchSum.
cpl cpl#_[a-b]YYMMDD
ex. cpl5_a001017
None None
ccsm ccsm#_# or ccsm#_#_beta#
ex. ccsm1_5 or ccsm2_0_beta12
None None
Note: Only the CCSM Coordinator can tag new CCSM versions. Currently we are not allowing global CCSM branches. We may maintain bug-fix branches for major CCSM model releases.
csim#_#_# csim#_#_#
ex. csim4_0_0
csim#_#_#_brnch_[name] csim#_#_#_brnchT_[name]#
Note: Branches are not currently being used, but may be in the future.
csm_share share#_#_#
share#_#_#_brnch_[name]_beta# share#_#_#_brnchT_[name]_beta#
Note: Only "ccsm-reps" have the ability to commit changes here. Changes should be made on branches first - to allow full testing before incorporating changes on the trunk. Since, "csm_share" is used by all component models both stand-alone and coupled - it's important that changes here be carefully tested and monitored.
dice dice#_[a-b]YYMMDD
ex. dice5_a001017
None None
dlnd dlnd#_[a-b]YYMMDD
ex. dlnd5_a001017
None None
docn docn#_[a-b]YYMMDD
ex. docn5_a001017
None None
latm latm#_[a-b]YYMMDD
ex. latm5_a001017
None None
pop POP_#_#_#
ex. POP_1_2
ex. ccsm_pop_1_2
ex. ccsm_pop_1_2_20001023a
Note: The main trunk is straight LANL POP. The "ccsm_pop" branches are for local NCAR modifications needed for CCSM releases. Additional branches may be added.
scripts scripts_[a-b]YYMMDD
ex. scripts_a001017
None None
Note: Only "ccsm-reps" can commit changes here.

Notes: Versions with "[a-b] refers to alpha and beta versions of a model release. Versions with #_#_# can also be just two digits (for example ccm3_10) in this case they refer to a major version that has gone through more rigorous testing.

next up previous contents
Next: 8 Shared and External Up: dev_guide Previous: 6 Coding Conventions   Contents