798649942a7bba8fb7571cdccb4952c02172d753
[privoxy.git] / doc / webserver / developer-manual / cvs.html
1 <HTML
2 ><HEAD
3 ><TITLE
4 >The CVS Repository</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
8 "><LINK
9 REL="HOME"
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
12 REL="PREVIOUS"
13 TITLE="Introduction"
14 HREF="introduction.html"><LINK
15 REL="NEXT"
16 TITLE="Documentation Guidelines"
17 HREF="documentation.html"><LINK
18 REL="STYLESHEET"
19 TYPE="text/css"
20 HREF="../p_doc.css"></HEAD
21 ><BODY
22 CLASS="SECT1"
23 BGCOLOR="#EEEEEE"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 SUMMARY="Header navigation table"
32 WIDTH="100%"
33 BORDER="0"
34 CELLPADDING="0"
35 CELLSPACING="0"
36 ><TR
37 ><TH
38 COLSPAN="3"
39 ALIGN="center"
40 >Privoxy Developer Manual</TH
41 ></TR
42 ><TR
43 ><TD
44 WIDTH="10%"
45 ALIGN="left"
46 VALIGN="bottom"
47 ><A
48 HREF="introduction.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 ></TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="documentation.html"
63 ACCESSKEY="N"
64 >Next</A
65 ></TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><DIV
72 CLASS="SECT1"
73 ><H1
74 CLASS="SECT1"
75 ><A
76 NAME="CVS">2. The CVS Repository</H1
77 ><P
78 >      If you intend to help us with programming, documentation or packaging
79       you will need write access to our holy grail, the CVS repository.
80       Please read this chapter completely before accessing via CVS.
81     </P
82 ><DIV
83 CLASS="SECT2"
84 ><H2
85 CLASS="SECT2"
86 ><A
87 NAME="CVSACCESS">2.1. Access to CVS</H2
88 ><P
89 >        The project's CVS repository is hosted on
90         <A
91 HREF="http://sourceforge.net/"
92 TARGET="_top"
93 >SourceForge.</A
94 >
95         Please refer to the chapters 6 and 7 in
96         <A
97 HREF="http://sourceforge.net/docman/?group_id=1"
98 TARGET="_top"
99 >SF's site
100         documentation</A
101 > for the technical access details for your
102         operating system. For historical reasons, the CVS server is
103         called <TT
104 CLASS="LITERAL"
105 >cvs.ijbswa.sourceforge.net</TT
106 >, the repository is
107         called <TT
108 CLASS="LITERAL"
109 >ijbswa</TT
110 >, and the source tree module is called
111         <TT
112 CLASS="LITERAL"
113 >current</TT
114 >.
115       </P
116 ></DIV
117 ><DIV
118 CLASS="SECT2"
119 ><H2
120 CLASS="SECT2"
121 ><A
122 NAME="CVSBRANCHES">2.2. Branches</H2
123 ><P
124 >       Within the CVS repository, there are modules and branches. As
125        mentioned, the sources are in the <TT
126 CLASS="LITERAL"
127 >current</TT
128 >
129        <SPAN
130 CLASS="QUOTE"
131 >"module"</SPAN
132 >. Other modules are present for platform specific
133        issues. There is a webview of the CVS hierarchy at <A
134 HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/"
135 TARGET="_top"
136 >http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/</A
137 >,
138        which might help with visualizing how these pieces fit together.
139      </P
140 ><P
141 >       Branches are used to fork a sub-development path from the main trunk.
142        Within the <TT
143 CLASS="LITERAL"
144 >current</TT
145 > module where the sources are, there
146        is always at least one <SPAN
147 CLASS="QUOTE"
148 >"branch"</SPAN
149 > from the main trunk
150        devoted to a stable release series. The main trunk is where active
151        development takes place for the next stable series (e.g. 3.2.x).
152        And for testing bugfixes for the stable series. Just prior to each
153        stable series (e.g. 3.0.x), a branch is created just for stable series
154        releases (e.g. 3.0.0 -&#62; 3.0.1 -&#62; 3.0.2, etc). Once the initial stable
155        release of any stable branch has taken place, this branch is
156        <SPAN
157 CLASS="emphasis"
158 ><I
159 CLASS="EMPHASIS"
160 >only used for bugfixes</I
161 ></SPAN
162 >, which have had prior
163        testing before being committed to CVS. (See <A
164 HREF="newrelease.html#VERSIONNUMBERS"
165 >Version Numbers</A
166 > below for details on
167        versioning.)
168      </P
169 ></DIV
170 ><DIV
171 CLASS="SECT2"
172 ><H2
173 CLASS="SECT2"
174 ><A
175 NAME="CVSCOMMIT">2.3. CVS Commit Guidelines</H2
176 ><P
177 >        The source tree is the heart of every software project. Every effort must
178         be made to ensure that it is readable, compilable and consistent at all
179         times. There are differing guidelines for the stable branch and the
180         main development trunk, and we ask anyone with CVS access to strictly
181         adhere to the following guidelines:
182       </P
183 ><P
184 >       Basic Guidelines, for all branches:
185       </P
186 ><P
187 >        <P
188 ></P
189 ><UL
190 ><LI
191 ><P
192 >            Never (read: <SPAN
193 CLASS="emphasis"
194 ><I
195 CLASS="EMPHASIS"
196 >never, ever</I
197 ></SPAN
198 >) be tempted to commit
199             that small change without testing it thoroughly first. When we're
200             close to a public release, ask a fellow developer to review your 
201             changes.
202           </P
203 ></LI
204 ><LI
205 ><P
206 >            Your commit message should give a concise overview of <SPAN
207 CLASS="emphasis"
208 ><I
209 CLASS="EMPHASIS"
210 >what you
211             changed</I
212 ></SPAN
213 > (no big details) and <SPAN
214 CLASS="emphasis"
215 ><I
216 CLASS="EMPHASIS"
217 >why you changed it</I
218 ></SPAN
219 >
220             Just check previous messages for good examples.
221           </P
222 ></LI
223 ><LI
224 ><P
225 >            Don't use the same message on multiple files, unless it equally applies to
226             all those files.
227           </P
228 ></LI
229 ><LI
230 ><P
231 >            If your changes span multiple files, and the code won't recompile unless
232             all changes are committed (e.g. when changing the signature of a function),
233             then commit all files one after another, without long delays in between.
234             If necessary, prepare the commit messages in advance.
235           </P
236 ></LI
237 ><LI
238 ><P
239 >            Before changing things on CVS, make sure that your changes are in line
240             with the team's general consensus on what should be done.
241           </P
242 ></LI
243 ><LI
244 ><P
245 >            Note that near a major public release, we get more cautious.
246             There is always the possibility to submit a patch to the <A
247 HREF="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse"
248 TARGET="_top"
249 >patch
250             tracker</A
251 > instead.
252           </P
253 ></LI
254 ></UL
255 >
256       </P
257 ><P
258 >       Stable branches are handled with decidedly more care, especially after
259        the initial *.*.0 release, and we are just in bugfix mode. In addition
260        to the above, the below applies only to the stable branch (currently
261        the v_3_0_branchpoint branch):
262       </P
263 ><P
264 >       <P
265 ></P
266 ><UL
267 ><LI
268 ><P
269 >          Do <SPAN
270 CLASS="emphasis"
271 ><I
272 CLASS="EMPHASIS"
273 >not commit anything</I
274 ></SPAN
275 > into the stable branch,
276           unless immediately before a new release! There needs to be testing 
277           done before it hits CVS, and to ensure that all changes are
278           appropriate just to fix whatever the problem is.
279         </P
280 ></LI
281 ><LI
282 ><P
283 >         Where possible, bugfixes and changes should be tested in the main 
284          development trunk first. There may be occasions where this is not 
285          feasible, though.
286         </P
287 ></LI
288 ><LI
289 ><P
290 >          Alternately, proposed changes can be submitted as patches to the patch tracker on 
291           Sourceforge first: <A
292 HREF="http://sourceforge.net/tracker/?group_id=11118&atid=311118"
293 TARGET="_top"
294 >http://sourceforge.net/tracker/?group_id=11118&#38;atid=311118</A
295 >.
296           Then ask for peer review. 
297         </P
298 ></LI
299 ><LI
300 ><P
301 >           Do not commit <SPAN
302 CLASS="emphasis"
303 ><I
304 CLASS="EMPHASIS"
305 >anything</I
306 ></SPAN
307 > unless your proposed
308            changes have been well tested first, by other members of the
309            project, and have prior approval of the project leaders or consensus
310            of the devel list.
311          </P
312 ></LI
313 ><LI
314 ><P
315 >          Do not even think about anything except bugfixes. No new features!
316          </P
317 ></LI
318 ></UL
319 >
320       </P
321 ></DIV
322 ></DIV
323 ><DIV
324 CLASS="NAVFOOTER"
325 ><HR
326 ALIGN="LEFT"
327 WIDTH="100%"><TABLE
328 SUMMARY="Footer navigation table"
329 WIDTH="100%"
330 BORDER="0"
331 CELLPADDING="0"
332 CELLSPACING="0"
333 ><TR
334 ><TD
335 WIDTH="33%"
336 ALIGN="left"
337 VALIGN="top"
338 ><A
339 HREF="introduction.html"
340 ACCESSKEY="P"
341 >Prev</A
342 ></TD
343 ><TD
344 WIDTH="34%"
345 ALIGN="center"
346 VALIGN="top"
347 ><A
348 HREF="index.html"
349 ACCESSKEY="H"
350 >Home</A
351 ></TD
352 ><TD
353 WIDTH="33%"
354 ALIGN="right"
355 VALIGN="top"
356 ><A
357 HREF="documentation.html"
358 ACCESSKEY="N"
359 >Next</A
360 ></TD
361 ></TR
362 ><TR
363 ><TD
364 WIDTH="33%"
365 ALIGN="left"
366 VALIGN="top"
367 >Introduction</TD
368 ><TD
369 WIDTH="34%"
370 ALIGN="center"
371 VALIGN="top"
372 >&nbsp;</TD
373 ><TD
374 WIDTH="33%"
375 ALIGN="right"
376 VALIGN="top"
377 >Documentation Guidelines</TD
378 ></TR
379 ></TABLE
380 ></DIV
381 ></BODY
382 ></HTML
383 >