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