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

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.
- CCSM liaison suggests a new version to the CCSM coordinator. The CCSM liaisons responsible for each component model monitor code changes and decide when changes are large enough to warrant a new CCSM. Any changes to the coupler or csm_share interface - however minor - are Enough to warrant a new CCSM version.
- CCSM coordinator specifies requirements for a new version. If global CCSM issues drive the creation of a new version, the CCSM coordinator will work with component model liaisons on a list of requirements for a new CCSM version. CCSM liaisons are responsible for making sure that all necessary changes are implemented.
CCSM liaison tests with last CCSM version
The CCSM liaison tests the new component version with the CCSM model system and ensure it works.
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 "ccsm-reps@cgd.ucar.edu" e-mail group with a short description of the changes.
Coordinator checks with each component
The CCSM coordinator checks with the other component liaisons to see if their components need to be updated.
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.
CCSM coordinator tags the new version
The CCSM coordinator tags the complete CCSM model system.
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 "ccsm-progs@cgd.ucar.edu" e-mail group.
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:

:ext:username@goldhill.cgd.ucar.edu:/fs/cgd/csm/models/CVS.REPOS

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 ccm#_#_#_brnch_[name]
ex. ccm1_10_brnch_bug_fix ccm#_#_#_brnchT_[name]#
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#_#_#
share2_0_1 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 ccsm_pop_#_#_#
ex. ccsm_pop_1_2 ccsm_pop_#_#_#_YYYYMMDD[a-z]
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: 8 Shared and External Up: dev_guide Previous: 6 Coding Conventions Contents

csm@ucar.edu

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.

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	ccm#_#_#_brnch_[name] ex. ccm1_10_brnch_bug_fix	ccm#_#_#_brnchT_[name]# 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#_#_# share2_0_1	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	ccsm_pop_#_#_# ex. ccsm_pop_1_2	ccsm_pop_#_#_#_YYYYMMDD[a-z] 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.