MITgcm CVS policy
Introduction
This note describes policies that apply to the MITGCM CVS repository.
Why have a policy?
CVS itself is a liberal free-for-all product that can be used in a
variety of ways. It is designed to provide a system for storing arbitrary
files in a way that allows the change history of the individual files to
be tracked. If CVS is used without any other policy the result can be a
collection of files each of which has complex, multiply branched set of
inter-related versions. This sort of CVS repository can be come like a
library where books are simply stored in a huge heap. Although nothing is
actually lost, the task of finding a coherent collection of material soon
becomes impossible.
The policies we employ address tree areas
- Maintaining an orderly and easily identifiable, coherent set of
evolving "products".
- Allowing concurrent, on-going development of product
components.
- Making the integration of achieved developments easy, rapid,
organized and clear.
Development trees and checkpoint trees
A directory within the MITGCM repository resides under either the development
branch or the checkpoint branch. Files within each branch follow different
policies.
Development tree policies
Development trees are intended to be flexible areas where arbitrary files
can be stored with multiple versions, many branches supporting multiple
ongoing streams of development. Development trees have no policies in
place to control complexity. Development trees might be associated with a
particular person, a certain project or a particular special piece of
work. These trees are intended to be useful areas for storing current work
and for archiving partially finished work so that it doesn't get mislaid
and so that some record of the development history can be easily
maintained. The only policy that applies to development trees is that this
style of tree is not intended to be used for providing a "checkpoint"
distribution. Tagged configurations of tools built from this style of tree
can be distributed, but because these trees do not have any policies
regarding testing of functionality, platform coverage or documentation
these trees are not allowed to form the basis of "checkpoint"
distributions or formal "releases". Other policies can be defined by
individuals users of these trees but there are no further global
policies. The MITGCM repository development_tree/ sub-directory is
reserved for holding development trees. Development trees also serve as
experimental areas for exploring new code management policies.
Checkpoint tree policies
Checkpoint trees are intended to provide structured storage areas for
holding code that is intended for open distribution and is to be readily
downloaded. There are policies governing the operation of these trees
which are designed to ensure that distributed codes are early identified
and meet certain levels of quality.
- Check-out: Just do it! Two mechanisms are available. cvsanon for
read only access and regular cvs co .... for read/write access.
- Check-in: The code check in procedure for a "checkpoint" tree
is as follows
- Check out the latest main branch revision.
- Merge your changes into that revision.
- Build and validate new code.
- Check that there have been no further changes to the
repository. Repeat from 2.1 if repository has changed.
- Get clearance from other developers to check in your
changes.
- Check in your changed main branch.
- Build and validate the new changes.
- Tag code as "checkpointNN". Add records to docs/tag-index.
- Build and validate test cases (see testing).
- Create and install checkpointNN.tar.gz
- Testing: Things in a checkpoint tree require a test case
that can be used to validate the component.
- Checkpoint tagging: No code should be left in limbo
(un-tagged) for extended periods. On the other hand it's unnecessary
to create a checkpoint tag for every little change. Checkpoint tags
should be made after a particularly significant code modification or
otherwise on a regular basis, say bi-weekly. Very often we set a
list of goals to be reached by the next checkpoint which sometimes
takes more than two weeks to achieve. Obviously, in this case a
bi-weekly checkpoint would not be useful.
- Release tagging: Releases are only based on checkpoint tree
code. Maintenance fixes to releases are also maintained within the
checkpoint tree. Files within a release must have accompanying
documentation. The form of this documentation depends on the file
type.
- Branches: Branches are a useful tool for making changes
prior to checkpoints without breaking other working versions but it
must be understood that branches are short-lived and that releases
and checkpoints not be made from a branch. Branches are especially
useful for adding totally
new features. bug-fixes to checkpoints
are introduced by moving checkpoint levels forward. The only
historical code maintenance that s employed is for fixes and patches
to formal releases - not checkpoints.
Someone checked-in broken code so not my code doesn't work?
You have several options:
- Politely email everyone at support@mitgcm.org asking what has
happened and that it be fixed?
- Figure out why the new code is broken, fix it, check it in and
proudly send a message to support@mitgcm.org to show how
constructive you are.
- Complain that the quality of work is too low and then do nothing
to fix the code.
We advise you to only use the third option if you are confident that
your own contributions to the code are bug-free, well written,
documented and fool proof. :)
These policies are causing me a big problem, what can I do?
The policies are not enforced by any mechanism other than mutual
agreement! If you think the policies are not appropriate then let us
know and we can discuss changing them. However, if you simply ignore the
policies regarding the checkpoint_release trees then your code may be
removed and/or your access revoked.
Questions
If you have any questions or suggestions please contact the MITgcm
developers at
MITgcm-support@mitgcm.org
|