MITgcm/mitgcm.org/cvspolicy.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.75 [en] (X11; U; Linux 2.2.14-5.0 i686) [Netscape]">
</head>
<body>

<h2>
Introduction</h2>
This note describes policies that apply to the MITGCM CVS repository.
<h2>
Why have a policy?</h2>
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.
<p>The policies we employ address two areas
<ol>
<li>
Maintaining an orderly and easily identifiable, coherent set of evolving
"products".</li>

<li>
Allowing concurrent, on-going development of product components.</li>
</ol>

<h2>
Development trees and checkpoint trees</h2>
A directory within the MITGCM repository resides under either the development
branch or the checkpoint branch. Files within each branch follow different
policies.
<h2>
Development tree policies</h2>
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 polcies regarding testing of functionality,
platform coverage or documentation these trees are not allowed to form
the basis of "checkpoint" distrbutions 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/ subdirectory is
reserved for holding development trees. Development trees also serve as
experimental areas for exploring new code management policies.
<h2>
Checkpoint tree policies</h2>
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.
<ol>
<li>
Check-out</li>

<br>Just do it! Two mechanisms are available. cvsanon for read only access
and regular cvs co .... for read/write access.
<li>
Check-in</li>

<br>The code check in procedure for a "checkpoint" tree is as follows
<ol>
<li>
Check out the latest main branch revision.</li>

<li>
Merge your changes into that revision.</li>

<li>
Build and validate new code.</li>

<li>
Check that there have been no further changes to the repository. Repeat
from 2.1 if repository has changed.</li>

<li>
Get clearance from other developers to check in your changes.</li>

<li>
Check in your changed main branch.</li>

<li>
Build and validate the new changes.</li>

<li>
Tag code as "checkpointNN". Add records to docs/tag-index.</li>

<li>
Build and validate test cases (see testing).</li>

<li>
Create and install checkpointNN.tar.gz</li>
</ol>

<li>
Testing</li>

<br>Things in a checkpoint tree require a test case that can be used to
validate the component.
<li>
Checkpoint tagging</li>

<br>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.
<li>
Release tagging</li>

<br>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.
<li>
Branches</li>

<br>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.</ol>

<h2>
These policies are causing me a big problem, what can I do?</h2>
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.
<h2>
What about bitkeeper</h2>
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!
<p>Questions, comments e-mail: code.czars@mitgcm.org
<br>
<hr WIDTH="100%">
<table CELLSPACING=0 CELLPADDING=0 WIDTH="100%" NOSAVE >
<tr NOSAVE>
<td><font size=-1>Last modified on $Date: $</font></td>

<td>
<div align=right><font size=-1>CVS: $Source: $Revision: $</font></div>
</td>
</tr>
</table>

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