<!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 "©"> <!-- kludge for docbook2man -->
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.
</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>
<!--
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.
</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
</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&group_id=11118&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&group_id=11118&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&atid=311118">http://sourceforge.net/tracker/?group_id=11118&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>
tracker</ulink> instead.
</para>
</sect2>
+ -->
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<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$
<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$
<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>
</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>
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.
projects / privoxy.git / commitdiff