From ec6fb54fafd88e7b7febf07aec687ae04dd57ccc Mon Sep 17 00:00:00 2001
From: hal9 <hal9@users.sourceforge.net>
Date: Thu, 26 Sep 2002 01:21:40 +0000
Subject: [PATCH] Porting 3.1.1 changes: more on cvs and branches, more on
 versions and releases.

---
 doc/source/developer-manual.sgml | 147 ++++++++++++++++++++++++++-----
 1 file changed, 126 insertions(+), 21 deletions(-)

diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 8c917f67..623f1ded 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -8,10 +8,10 @@
 <!entity contacting SYSTEM "contacting.sgml">
 <!entity copyright SYSTEM "copyright.sgml">
 <!entity license SYSTEM "license.sgml">
-<!entity p-version "2.9.20">
-<!entity p-status "beta">
-<!entity % p-not-stable "INCLUDE">
-<!entity % p-stable "IGNORE">
+<!entity p-version "3.0.0">
+<!entity p-status "stable">
+<!entity % p-not-stable "IGNORE">
+<!entity % p-stable "INCLUDE">
 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
 <!entity  my-copy "&copy;">        <!-- kludge for docbook2man            -->
@@ -23,7 +23,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 
- $Id: developer-manual.sgml,v 1.46.2.7 2002/08/14 17:29:25 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $
 
  Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
  See LICENSE.
@@ -50,7 +50,7 @@
     </pubdate>
 
 
-    <pubdate>$Id: developer-manual.sgml,v 1.46.2.7 2002/08/14 17:29:25 hal9 Exp $</pubdate>
+    <pubdate>$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $</pubdate>
 
 <!--
 
@@ -140,6 +140,12 @@ Hal.
       url="mailto:developers@privoxy.org">the list</ulink> and wait until a
       project manager has added you.
     </para>
+    <para>
+     You will also need to have a cvs package installed, which will 
+     entail having ssh installed as well (which seems to be a requirement of
+     SourceForge), in order to access the cvs repository. Having the GNU build
+     tools is also going to be important (particularly, autoconf and gmake).
+    </para>
     <para>
       For the time being (read, this section is under construction), please
       refer to the extensive comments in the source code.
@@ -169,12 +175,45 @@ Hal.
       </para>
     </sect2>
 
-    <sect2 id="cvscommit"><title>CVS Commit Guideline</title>
+    <sect2 id="cvsbranches">
+    <title>Branches</title>
+     <para>
+       Within the CVS repository, there are modules and branches. As
+       mentioned, the sources are in the <literal>current</literal>
+       <quote>module</quote>. Other modules are present for platform specific
+       issues. There is a webview of the CVS hierarchy at <ulink
+       url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/</ulink>,
+       which might help with visualizing how these pieces fit together.
+     </para>
+     <para>
+       Branches are used to fork a sub-development path from the main trunk.
+       Within the <literal>current</literal> module where the sources are, there
+       is always at least one <quote>branch</quote> from the main trunk
+       devoted to a stable release series. The main trunk is where active
+       development takes place for the next stable series (e.g. 3.2.x).
+       So just prior to each stable series (e.g. 3.0.x), a branch is created
+       just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc).
+       Once the initial stable release of any stable branch has taken place,
+       this branch is <emphasis>only used for bugfixes</emphasis>, which have
+       had prior testing before being committed to CVS. (See <link
+       linkend="versionnumbers">Version Numbers</link> below for details on
+       versioning.)
+     </para>
+    </sect2>
+
+    <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
       <para>
         The source tree is the heart of every software project. Every effort must
         be made to ensure that it is readable, compilable and consistent at all
-        times. We therefore ask anyone with CVS access to strictly adhere to the
-        following guidelines:
+        times. There are differing guidelines for the stable branch and the
+        main development trunk, and we ask anyone with CVS access to strictly
+        adhere to the following guidelines:
+      </para>
+      
+      <para>
+       Basic Guidelines, for all branches:
+      </para>
+      <para>
         <itemizedlist>
           <listitem><para>
             Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
@@ -199,23 +238,68 @@ Hal.
           </para></listitem>
           <listitem><para>
             Before changing things on CVS, make sure that your changes are in line
-            with the team's general consensus on what should be done (see below).
+            with the team's general consensus on what should be done.
           </para></listitem>
-          <listitem><para>
-            Don't commit into the stable branch, unless immediately before a new
-            release. (See <link linkend="versionnumbers">Version Numbers</link> below
-            for details.) Collect your changes on the <ulink
-            url="http://sourceforge.net/tracker/?atid=311118&amp;group_id=11118&amp;func=browse">patches
+          <listitem>
+           <para>
+            Note that near a major public release, we get more cautious.
+            There is always the possibility to submit a patch to the <ulink
+            url="http://sourceforge.net/tracker/?atid=311118&amp;group_id=11118&amp;func=browse">patch
             tracker</ulink> instead.
-          </para></listitem>
+          </para>
+         </listitem> 
         </itemizedlist>
       </para>
+      
+      <para>
+       Stable branches are handled with more care, especially after the 
+       initial *.*.0 release, and we are just in bugfix mode. In addition to 
+       the above, the below applies only to the stable branch (currently the 
+       v_3_0_branchpoint branch):
+      </para>
+      
+      <para>
+       <itemizedlist>
+        <listitem><para>
+          Do <emphasis>not commit anything</emphasis> into the stable branch,
+          unless immediately before a new release! There needs to be testing 
+          done before it hits CVS, and to ensure that all changes are
+          appropriate just to fix whatever the problem is.
+        </para></listitem>
+       <listitem>
+        <para>
+          Submit any proposed changes as patches first to the patch tracker on 
+          Sourceforge: <ulink url="http://sourceforge.net/tracker/?group_id=11118&#38;atid=311118">http://sourceforge.net/tracker/?group_id=11118&#38;atid=311118</ulink>.
+          Then ask for peer review.
+        </para>
+       </listitem> 
+        <listitem>
+         <para>
+           Do not commit <emphasis>anything</emphasis> unless your patches
+           been well tested first, by other members of the project, 
+           and has prior approval of the project leaders or consensus of the
+           devel list.
+         </para>
+        </listitem> 
+        <listitem>
+         <para>
+          Do not even think about anything except bugfixes. No new features!
+         </para>
+        </listitem> 
+     
+       </itemizedlist>
+      </para> 
     </sect2>
 
+<!--
+ This sounds vague, dated, and out of step with current development style.
+ Removing 09/03/02, HB.
+
     <sect2 id="cvswhenask"><title>Discussing Changes First</title>
       <para>
-        We don't have a too formal policy on this, just use common sense. Hints: If it is..
-        <orderedlist numeration="arabic">
+        We don't have a formal policy for the development branch, just use
+        common sense. Hints: If it is.. 
+       <orderedlist numeration="arabic">
           <listitem><para>
             ..a bug-fix / clean-up / cosmetic thing: shoot
           </para></listitem>
@@ -242,6 +326,7 @@ Hal.
         tracker</ulink> instead.
       </para>
     </sect2>
+   --> 
   </sect1>
 	
   <!--   ~~~~~       New section      ~~~~~     -->
@@ -1750,7 +1835,7 @@ static void unload_re_filterfile( void *f ) { ... }</programlisting>
 
     <para><emphasis>Example for file comments:</emphasis></para>
 <programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.7 2002/08/14 17:29:25 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $";
 /*********************************************************************
  *
  * File        :  $S<!-- Break CVS Substitution -->ource$
@@ -1810,7 +1895,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
 <programlisting>
 #ifndef _FILENAME_H
 #define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.7 2002/08/14 17:29:25 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $"
 /*********************************************************************
  *
  * File        :  $S<!-- Break CVS Substitution -->ource$
@@ -1988,7 +2073,7 @@ at sourceforge. Three simple steps:
     <para>
       First you need to determine which version number the release will have. 
       <application>Privoxy</application> version numbers consist of three numbers,
-      separated by dots, like in X.Y.Z, where:
+      separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
         <itemizedlist>
           <listitem>
             <para>
@@ -2030,6 +2115,22 @@ at sourceforge. Three simple steps:
           </listitem>
         </itemizedlist>
     </para>
+    <para>
+     In summary, the main CVS trunk is the development branch where new
+     features are being worked on for the next stable series. This should
+     almost always be where the most activity takes place. There is always at
+     least one stable branch from the trunk, e.g now it is 3.0, which is only
+     used to release stable versions. Once the initial .0 release of the
+     stable branch has been done, then as a rule, only bugfixes that have had
+     prior testing should be committed to the stable branch. At that point, it
+     is mostly <quote>hands off</quote>. Once there are enough bugfixes to
+     justify a new release, the version of this branch is again incremented 
+     Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable releases from within
+     the stable branch. 3.1.x is currently the main trunk, and where work on
+     3.2.x is taking place. If any questions, please post to the devel list
+     <emphasis>before</emphasis> committing to a stable branch!
+
+    </para>
 
     </sect2>
      
@@ -2888,6 +2989,10 @@ at sourceforge. Three simple steps:
   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
   $Log: developer-manual.sgml,v $
+  Revision 1.46.2.8  2002/08/17 00:16:10  hal9
+  Add note on updating webserver for User-manual/CGI editor, which is version
+  dependent (and different from main UM link).
+
   Revision 1.46.2.7  2002/08/14 17:29:25  hal9
   Add small notes on post-release steps, and uploading docs to webserver.
 
-- 
2.49.0