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.76 [en] (X11; U; Linux 2.4.1 i686) [Netscape]">
   <meta name="Author" content="Chris Hill">
   <title>MITgcm CVS policy</title>
</head>
<body text="#000000" bgcolor="#FF99FF" link="#0000EF" vlink="#51188E" alink="#FF0000">

<center>
<h1>
MITgcm CVS policy</h1></center>

<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 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.
<p>The policies we employ address tree 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>

<li>
Making the integration&nbsp; of achieved developments easy, rapid, organized
and clear.</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 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.
<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 (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.
<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 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
<br>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.</ol>

<h2>
Someone checked-in broken code so not my code doesn't work?</h2>
You have several options:
<ol>
<li>
Politely email everyone at support@mitgcm.org asking what&nbsp; has happened
and that it be fixed?</li>

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

<li>
Complain that the quality of work is too low and then do nothing to fix
the code.<br>
<BR></li>

<br>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.&nbsp; :)</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: 2001/02/17 17:08:40 $</font></td>

<td>
<div align=right><font size=-1>CVS: $Source: /u/gcmpack/mitgcm.org/../cvspolicy.html,v
$Revision: 1.10 $</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	jmc	1.9	<meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.4.1 i686) [Netscape]">
6	adcroft	1.8	<meta name="Author" content="Chris Hill">
7			<title>MITgcm CVS policy</title>
8	cnh	1.2	</head>
9	adcroft	1.8	<body text="#000000" bgcolor="#FF99FF" link="#0000EF" vlink="#51188E" alink="#FF0000">
10
11			<center>
12			<h1>
13	jmc	1.9	MITgcm CVS policy</h1></center>
14	cnh	1.1
15	adcroft	1.7	<h2>
16			Introduction</h2>
17			This note describes policies that apply to the MITGCM CVS repository.
18			<h2>
19			Why have a policy?</h2>
20			CVS itself is a liberal free-for-all product that can be used in a variety
21			of ways. It is designed to provide a system for storing arbitrary files
22			in a way that allows the change history of the individual files to be tracked.
23			If CVS is used without any other policy the result can be a collection
24	jmc	1.9	of files each of which has complex, multiply branched set of inter-related
25	adcroft	1.7	versions. This sort of CVS repository can be come like a library where
26			books are simply stored in a huge heap. Although nothing is actually lost,
27			the task of finding a coherent collection of material soon becomes impossible.
28	jmc	1.9	<p>The policies we employ address tree areas
29	adcroft	1.7	<ol>
30			<li>
31			Maintaining an orderly and easily identifiable, coherent set of evolving
32			"products".</li>
33
34			<li>
35			Allowing concurrent, on-going development of product components.</li>
36	jmc	1.9
37			<li>
38			Making the integration  of achieved developments easy, rapid, organized
39			and clear.</li>
40	adcroft	1.7	</ol>
41
42			<h2>
43			Development trees and checkpoint trees</h2>
44			A directory within the MITGCM repository resides under either the development
45			branch or the checkpoint branch. Files within each branch follow different
46			policies.
47			<h2>
48			Development tree policies</h2>
49			Development trees are intended to be flexible areas where arbitrary files
50			can be stored with multiple versions, many branches supporting multiple
51			ongoing streams of development. Development trees have no policies in place
52			to control complexity. Development trees might be associated with a particular
53			person, a certain project or a particular special piece of work. These
54			trees are intended to be useful areas for storing current work and for
55			archiving partially finished work so that it doesn't get mislaid and so
56			that some record of the development history can be easily maintained. The
57			only policy that applies to development trees is that this style of tree
58			is not intended to be used for providing a "checkpoint" distribution. Tagged
59			configurations of tools built from this style of tree can be distributed,
60	jmc	1.9	but because these trees do not have any policies regarding testing of functionality,
61	adcroft	1.7	platform coverage or documentation these trees are not allowed to form
62	jmc	1.9	the basis of "checkpoint" distributions or formal "releases". Other policies
63	adcroft	1.7	can be defined by individuals users of these trees but there are no further
64	jmc	1.9	global policies. The MITGCM repository development_tree/ sub-directory
65			is reserved for holding development trees. Development trees also serve
66			as experimental areas for exploring new code management policies.
67	adcroft	1.7	<h2>
68			Checkpoint tree policies</h2>
69			Checkpoint trees are intended to provide structured storage areas for holding
70			code that is intended for open distribution and is to be readily downloaded.
71			There are policies governing the operation of these trees which are designed
72			to ensure that distributed codes are early identified and meet certain
73			levels of quality.
74			<ol>
75			<li>
76			Check-out</li>
77
78			<br>Just do it! Two mechanisms are available. cvsanon for read only access
79			and regular cvs co .... for read/write access.
80			<li>
81			Check-in</li>
82
83			<br>The code check in procedure for a "checkpoint" tree is as follows
84			<ol>
85			<li>
86			Check out the latest main branch revision.</li>
87
88			<li>
89			Merge your changes into that revision.</li>
90
91			<li>
92			Build and validate new code.</li>
93
94			<li>
95			Check that there have been no further changes to the repository. Repeat
96			from 2.1 if repository has changed.</li>
97
98			<li>
99			Get clearance from other developers to check in your changes.</li>
100
101			<li>
102			Check in your changed main branch.</li>
103
104			<li>
105			Build and validate the new changes.</li>
106
107			<li>
108			Tag code as "checkpointNN". Add records to docs/tag-index.</li>
109
110			<li>
111			Build and validate test cases (see testing).</li>
112
113			<li>
114			Create and install checkpointNN.tar.gz</li>
115			</ol>
116
117			<li>
118			Testing</li>
119
120			<br>Things in a checkpoint tree require a test case that can be used to
121			validate the component.
122			<li>
123			Checkpoint tagging</li>
124
125	jmc	1.9	<br>No code should be left in limbo (un-tagged) for extended periods. On
126			the other hand it's unnecessary to create a checkpoint tag for every little
127			change. Checkpoint tags should be made after a particularly significant
128			code modification or otherwise on a regular basis, say bi-weekly. Very
129			often we set a list of goals to be reached by the next checkpoint which
130			sometimes takes more than two weeks to achieve. Obviously, in this case
131			a bi-weekly checkpoint would not be useful.
132	adcroft	1.7	<li>
133			Release tagging</li>
134
135			<br>Releases are only based on checkpoint tree code. Maintenance fixes
136			to releases are also maintained within the checkpoint tree. Files within
137			a release must have accompanying documentation. The form of this documentation
138			depends on the file type.
139			<li>
140			Branches</li>
141
142	jmc	1.9	<br>Branches are a useful tool for making changes prior to checkpoints
143			without breaking other working versions but it must be understood that
144			branches are short-lived and that releases and checkpoints not be made
145			from a branch. Branches are especially useful for adding totally
146			<br>new features. bug-fixes to checkpoints are introduced by moving checkpoint
147			levels forward. The only historical code maintenance that s employed is
148			for fixes and patches to formal releases - not checkpoints.</ol>
149
150	jmc	1.10	<h2>
151			Someone checked-in broken code so not my code doesn't work?</h2>
152	jmc	1.9	You have several options:
153			<ol>
154			<li>
155			Politely email everyone at support@mitgcm.org asking what  has happened
156			and that it be fixed?</li>
157
158			<li>
159			Figure out why the new code is broken, fix it, check it in and proudly
160			send a message to support@mitgcm.org to show how constructive you are.</li>
161
162			<li>
163			Complain that the quality of work is too low and then do nothing to fix
164			the code.<br>
165			<BR></li>
166
167			<br>We advise you to only use the third option if you are confident that
168			your own contributions to the code are bug-free, well written, documented
169			and fool proof.  :)</ol>
170	adcroft	1.7
171			<h2>
172			These policies are causing me a big problem, what can I do?</h2>
173			The policies are not enforced by any mechanism other than mutual agreement!
174			If you think the policies are not appropriate then let us know and we can
175			discuss changing them. However, if you simply ignore the policies regarding
176			the checkpoint_release trees then your code may be removed and/or your
177			access revoked.
178			<h2>
179			What about bitkeeper</h2>
180			We are looking at bitkeeper (www.bitkeeper.com). It looks cool, but policies
181			are still important. Any experience, suggestions let us know. Watch this
182			space!
183			<p>Questions, comments e-mail: code.czars@mitgcm.org
184			<br>
185			<hr WIDTH="100%">
186			<table CELLSPACING=0 CELLPADDING=0 WIDTH="100%" NOSAVE >
187			<tr NOSAVE>
188	jmc	1.11	<td><font size=-1>Last modified on $Date: 2001/02/17 17:08:40 $</font></td>
189	adcroft	1.7
190			<td>
191	adcroft	1.8	<div align=right><font size=-1>CVS: $Source: /u/gcmpack/mitgcm.org/../cvspolicy.html,v
192	jmc	1.11	$Revision: 1.10 $</font></div>
193	adcroft	1.7	</td>
194			</tr>
195			</table>
196	cnh	1.1
197	cnh	1.2	</body>
198			</html>