Development Guidelines

From OpenGrADS
Jump to: navigation, search

This page describes sevel policies and common sense rules for managing the several activities in the project.

CVS Policy[edit]

There are three main directories/modules in the OpenGrADS CVS repository:

  • cola - GrADS sources as obtained from COLA, as is, no patches
  • contrib - the core of the OpenGrADS specific development goes on here: interfaces and user defined extensions
  • grads - GrADS sources as obtained from COLA, plus local patches
  • Grads - the same as grads but includes the extensions/ subdirectory; this is the CVS modules used to build The OpenGrADS Bundle.
  • supplibs - the supplemental libs necessary for binary distribution of GrADS
  • Wgrib2 - The Wgrib2 utility by Wes Ebisuzaki, plus local patches

The configuration management of each one of these are slightly different.


The grads/Grads modules[edit]

The OpenGrADS Project is committed to closely track the development of the main GrADS engine by the core development group at COLA. A concerted effort will be made to import in the OpenGRADS repository every new release by COLA, in a proper vendor branch. Currently, COLA releases of GrADS v2 are being maintained as is in module cola/, and manually merged into this module. There has been no GrADS v1.9 relass by COLA since the start of the OpenGrADS project. OpenGrADS specific development of GrADS v2.0 is being conducted in module grads, on the TRUNK. GrADS v1.x specific development is being conduct on the GRADS1_DEV_BRANCH within this same module. The companion module Grads/ is the same as grads/ but includes the addional extensions/ containing the OpenGrADS User Defined Extensions. This is the module used for building the OpenGrADS Bundle.

Here are a few important points to keep in mind:

  • Please use branches sparingly. Place individual files on branches, not the whole directory. This facilitates comparison of tags via cvs update.
  • Once a file have been patched and committed on the branch, issue a tag which identifies the COLA version of origin. For example, if the cola release is v1.9.3, and this is the first OpenGrADS patch to that tag, use he string .oga.n to indicate the OpenGraDS patch level n:
 % cvs tag grads-2_0_a3-oga-1
  • When introducing an OpenGRaDS specific patch, make sure to alter the configure.ac file to indicate the revised version. Use the oga.n string to separate the COLA version number from the OpenGrADS patch level. In the example above, the new version would be "2.0.a3.oga.1".
The old GRADS2_DEV_BRANCH
Prior to April 2009, GrADS v2.0 development was conducted under the GRADS2_DEV_BRANCH. This module has been retired and v2.0 development has been switched to the TRUNK. The v1.x development, previously on the TRUNK, is now on its own separate branch: GRADS1_DEV_BRANCH.

The cola/ module[edit]

The cola/ module is being used exclusively for tracking GrADS v2 released by COLA as is. No local patches are currently being applied in this directory. OpenGrADS specific development of GrADS v2 is being maintained in module Grads/, currently on the TRUNK.

When importing new COLA releases, use "COLA" as the vendor branch, and specify the release tag to identify the particular COLA version. For example,

 % cvs import -m 'xxx: latest grads release v2.0.a5' grads COLA rel-2_0_a6

where xxx are the developer's initials. Please use the -m option to enter any useful information identifying the COLA release, such as fixes station data bug.

The supplibs/ module[edit]

This module contains the optional Supplemental Libraries needed for building GrADS. Specific information for this module can be found at Supplemental Libraries (Supplibs).

The contrib/ module[edit]

This is the module containg all the source code for the OpenGrADS extensions (such as user defned commands and user defined functions) and interfaces to other software, including perl, python, java, idl, matlab, php nd TCL. See OpenGrADS Documentation for additional information.

Developer experimental branches[edit]

Individual developers are encouraged to create branches for keeping experimental versions for their own use. As with the OPENGRADS_DEV_BRANCH described above, individual modified files should be placed into a branch, and not the whole directory. For example, an user named Joe modifies files gauser.c and gafunc.c under Grads/src then these 2 files (and these 2 files only) and place on a developer owned branch:

  % cd Grads/src
  % cvs tag -b JOE_DEV_BRANCH gauser.c gafunc.c   (create new branch, do this only once)
  % cvs upd -r JOE_DEV_BRANCH gauser.c gafunc.c   (so that next commit will go here)
  % cvs ci -m 'joe: added some experimental features' gauser.c gafunc.c

f those modifications are intented to be merged into the main development branches, then the user should post a message to opengrads-devel@lists.sf.net and discuss the patch/request a merge.

Contributions from non-project members[edit]

We are still to come up with a policy for this. For now the best approach is discuss your contribution on the opengrads-devel@lists.sf.net and a developer will check your contribution in for you.