1 |
edhill |
1.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 |
|
|
|