doc/webserver/developer-manual/cvs.html

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