MITgcm/mitgcm.org/cvspolicy.html

<html>
<head>
</head>
<body>
         MITGCM CVS policies
         ===================

o Introduction

  This note describes policies that apply to the MITGCM CVS repository
 
o 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 
  interelated 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 two areas 
    1. Maintaining an orderly and easily identifiable, coherent set of 
       evolving "products".
    2. Allowing concurrent, on-going development of product components.
  
o 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.
  
o 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 s 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
  polcies regarding testing of functionality, platform coverage or 
  documentation these trees are not allowed to form the basis of 
  "checkpoint" distrbutions or formal model releases. Other policies can 
  be defined by individuals users of these trees but there are no further 
  global policies. The MITGCM repository development/ subdirectory is 
  reserved for holding development trees. Development trees also serve as 
  experimental areas for exploring new code management policies.

o 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 clearly 
  identified and meet certain levels of quality.

  1. Check-out

     Just do it! Two mechanisms are available. cvsanon for read only access
     and regular cvs co .... for read/write access.

  2. Check-in.

     The code check in procedure for a "checkpoint" tree is as follows
     2.1  Check out the latest main branch revision.
     2.2  Merge your changes into that revision.
     2.3  Build and validate new code. 
     2.4  Check that there have been no further changes to the
          repository. Repeat from 2.1 if repository has changed.
     2.5  Get clearance from other developers to check in your changes.
     2.6  Check in your changed main branch.
     2.8  Build and validate the new changes.
     2.9  Tag code as "checkpointNN". Add records to docs/tag-index.
     2.10 Build and validate test cases (see testing).
     2.11 Create and install checkpointNN.tar.gz

  3. Testing

     Things in a checkpoint tree require a test case that
     can be used to validate the component. 

  4. Checkpoint tagging

     No code should be left in limbo. Checking in code and then
     leaving it in the repository untagged is bad. When you check
     in code you are creating a new checkpoint. That means you don't
     check in some code which you "know" works 100% and then go away 
     for two weeks. When you start checking in code you make sure
     you have time to do the process end-to-end as described in section
     2.

  5. 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.

  6. Branches

     Branches are to be used for bug-fixes and code patches to releases 
     only. All other changes e.g. totally new features, bug-fixes to 
     checkpoints are introduced by moving checkpoint levels forward. The 
     only historical code maintenance that is employed is for fixes and 
     patches to formal releases - not checkpoints.

o 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.

o What about bitkeeper

  We are looking at bitkeeper (www.bitkeeper.com). It looks cool, but 
  policies are still important. Any experience, suggestions let us know. 
  Watch this space!

Questions, comments e-mail: code.czars@mitgcm.org
</body>
</html>
1	cnh	1.2	<html>
2			<head>
3			</head>
4			<body>
5	cnh	1.3	MITGCM CVS policies
6			===================
7	cnh	1.1
8			o Introduction
9
10	cnh	1.3	This note describes policies that apply to the MITGCM CVS repository
11	cnh	1.1
12			o Why have a policy?
13
14			CVS itself is a liberal free-for-all product that can be used in a variety
15			of ways. It is designed to provide a system for storing arbitrary files
16			in a way that allows the change history of the individual files to be
17			tracked. If CVS is used without any other policy the result can be a
18			collection of files each of which has complex, multiply branched set of
19			interelated versions. This sort of CVS repository can be come like a
20	cnh	1.2	library where books are simply stored in a huge heap. Although nothing is
21			actually lost, the task of finding a coherent collection of material soon
22	cnh	1.1	becomes impossible.
23
24			The policies we employ address two areas
25			1. Maintaining an orderly and easily identifiable, coherent set of
26			evolving "products".
27	cnh	1.4	2. Allowing concurrent, on-going development of product components.
28	cnh	1.1
29			o Development trees and checkpoint trees
30
31	cnh	1.3	A directory within the MITGCM repository resides under either the
32	cnh	1.1	development branch or the checkpoint branch. Files within each branch
33			follow different policies.
34
35			o Development tree policies
36
37			Development trees are intended to be flexible areas where arbitrary files
38			can be stored with multiple versions, many branches supporting multiple
39			ongoing streams of development. Development trees have no policies in
40			place to control complexity. Development trees might be associated with
41			a particular person, a certain project or a particular special piece of
42			work. These trees are intended to be useful areas for storing current
43			work and for archiving partially finished work so that it doesn't get
44			mislaid and s that some record of the development history can be easily
45			maintained. The only policy that applies to development trees is that
46			this style of tree is not intended to be used for providing a
47			"checkpoint" distribution. Tagged configurations of tools built from this
48			style of tree can be distributed, but because these trees do not have any
49			polcies regarding testing of functionality, platform coverage or
50			documentation these trees are not allowed to form the basis of
51			"checkpoint" distrbutions or formal model releases. Other policies can
52			be defined by individuals users of these trees but there are no further
53	cnh	1.3	global policies. The MITGCM repository development/ subdirectory is
54	cnh	1.1	reserved for holding development trees. Development trees also serve as
55			experimental areas for exploring new code management policies.
56
57			o Checkpoint tree policies
58
59			Checkpoint trees are intended to provide structured storage areas for
60			holding code that is intended for open distribution and is to be readily
61			downloaded. There are policies governing the operation of these trees
62			which are designed to ensure that distributed codes are clearly
63			identified and meet certain levels of quality.
64
65			1. Check-out
66
67			Just do it! Two mechanisms are available. cvsanon for read only access
68			and regular cvs co .... for read/write access.
69
70			2. Check-in.
71
72			The code check in procedure for a "checkpoint" tree is as follows
73			2.1 Check out the latest main branch revision.
74			2.2 Merge your changes into that revision.
75			2.3 Build and validate new code.
76			2.4 Check that there have been no further changes to the
77			repository. Repeat from 2.1 if repository has changed.
78			2.5 Get clearance from other developers to check in your changes.
79			2.6 Check in your changed main branch.
80			2.8 Build and validate the new changes.
81			2.9 Tag code as "checkpointNN". Add records to docs/tag-index.
82			2.10 Build and validate test cases (see testing).
83			2.11 Create and install checkpointNN.tar.gz
84
85			3. Testing
86
87	cnh	1.2	Things in a checkpoint tree require a test case that
88			can be used to validate the component.
89
90	cnh	1.1	4. Checkpoint tagging
91
92	cnh	1.2	No code should be left in limbo. Checking in code and then
93			leaving it in the repository untagged is bad. When you check
94			in code you are creating a new checkpoint. That means you don't
95			check in some code which you "know" works 100% and then go away
96			for two weeks. When you start checking in code you make sure
97			you have time to do the process end-to-end as described in section
98			2.
99
100	cnh	1.1	5. Release tagging
101
102	cnh	1.2	Releases are only based on checkpoint tree code. Maintenance fixes
103			to releases are also maintained within the checkpoint tree. Files
104			within a release must have accompanying documentation. The form of this
105			documentation depends on the file type.
106
107	cnh	1.1	6. Branches
108
109			Branches are to be used for bug-fixes and code patches to releases
110			only. All other changes e.g. totally new features, bug-fixes to
111			checkpoints are introduced by moving checkpoint levels forward. The
112			only historical code maintenance that is employed is for fixes and
113			patches to formal releases - not checkpoints.
114
115			o These policies are causing me a big problem, what can I do?
116
117			The policies are not enforced by any mechanism other than mutual
118			agreement! If you think the policies are not appropriate then let us know
119			and we can discuss changing them. However, if you simply ignore the
120			policies regarding the checkpoint_release trees then your code may be
121			removed and/or your access revoked.
122
123			o What about bitkeeper
124
125			We are looking at bitkeeper (www.bitkeeper.com). It looks cool, but
126			policies are still important. Any experience, suggestions let us know.
127			Watch this space!
128
129	cnh	1.3	Questions, comments e-mail: code.czars@mitgcm.org
130	cnh	1.2	</body>
131			</html>