<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
-<!entity p-version "2.9.15">
-<!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.51 2002/05/29 00:30:59 mal0rd Exp $
+ $Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 hal9 Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
========================================================================
NOTE: Please read developer-manual/documentation.html before touching
- anything in this, or other Privoxy documentation.
+ anything in this, or other Privoxy documentation. You have been warned!
+ Failure to abide by this rule will result in the revocation of your license
+ to live a peaceful existence!
========================================================================
-->
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.51 2002/05/29 00:30:59 mal0rd Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 hal9 Exp $</pubdate>
<!--
<!-- end boilerplate -->
<para>
+ Please note that this document is constantly evolving. This copy represents
+ the state at the release of version &p-version;.
You can find the latest version of the this manual at <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
Please see <link linkend="contact">the Contact section</link>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="quickstart"><title>Quickstart to Privoxy Development</title>
+ <!--
<para>
You'll need an account on <ulink
url="http://sourceforge.net/">Sourceforge</ulink> to support our
url="mailto:developers@privoxy.org">the list</ulink> and wait until a
project manager has added you.
</para>
+ -->
+ <para>
+ The first step is to join the <ulink
+ url="mailto:developers@privoxy.org">developer's mailing list</ulink>.
+ You can submit your ideas, or even better patches. Patches are best
+ submitted to the Sourceforge tracker set up for this purpose, but
+ can be sent to the list for review too.
+ </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.
+ For the time being (read, this section is under construction), you can
+ also refer to the extensive comments in the source code. In fact,
+ reading the code is recommended in any case.
</para>
</sect2>
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="cvs"><title>The CVS Repository</title>
<para>
- If you intend to help us with programming, documentation or packaging
- you will need write access to our holy grail, the CVS repository.
- Please read this chapter completely before accessing via CVS.
+ If you become part of the active development team, you will eventually
+ need write access to our holy grail, the CVS repository. One of the
+ team members will need to set this up for you. Please read
+ this chapter completely before accessing via CVS.
</para>
<sect2 id="cvsaccess"><title>Access to CVS</title>
</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>
+ <para>
+ This will result in at least two active branches, which means there may
+ be occasions that require the same (or similar) item to be
+ checked into to two different places (assuming its a bugfix and needs
+ fixing in both the stable and unstable trees). This also means that in
+ order to have access to both trees, both will have to be checked out
+ separately. Use the <literal>cvs -r</literal> flag to check out a
+ branch, e.g: <literal>cvs co -r v_3_0_branch current</literal>.
+ </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>
+ 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>
</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
+ <literal>v_3_0_branch</literal> branch):
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Do not commit <emphasis>anything</emphasis> unless your proposed
+ changes have been well tested first, preferably by other members of the
+ project, or have prior approval of the project leaders or consensus
+ of the devel list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Where possible, bugfixes and changes should be tested in the main
+ development trunk first. There may be occasions where this is not
+ feasible, though.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Alternately, proposed changes can be submitted as patches to the patch tracker on
+ Sourceforge first: <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 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 ~~~~~ -->
variation on this file, <filename>privoxy-index.html</filename>,
meant for inclusion with doc packages), are maintained as SGML as well.
<emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
- contact someone involved in the documentation (at present Stefan and
- Hal).
+ contact someone involved in the documentation (at present Hal).
</para>
<para>
<filename>config</filename> requires some special handling. The reason it
which should be reviewed for errors and mis-formatting. Once satisfied
that it is correct, then it should be hand copied to
<filename>config</filename>.
-
</para>
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<listitem><para>
First, build the docs by running <computeroutput>make
dok</computeroutput> (or alternately <computeroutput>make
- redhat-dok</computeroutput>).
+ redhat-dok</computeroutput>). For PDF docs, do <computeroutput>make
+ dok-pdf</computeroutput>.
</para></listitem>
<listitem><para>
Run <computeroutput>make webserver</computeroutput> which copies all
<listitem>
<para>
Our documents are available in differing formats. Right now, they
- are just plain text, and HTML, but PDF, and others is always a
+ are just plain text, TML, and PDF, but others are always a
future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 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.4 2002/05/29 00:30:59 mal0rd Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 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>
This ensures that builds from CVS snapshots are easily distinguished from released versions.
The point version is reset to zero when the minor changes.
</para>
+ <para>
+ Stable branches work a little differently, since there should be
+ little to no development happening in such branches. Remember,
+ only bugfixes, which presumably should have had some testing
+ before being committed. Stable branches will then have their
+ version reported as <literal>0.0.0</literal>, during that period
+ between releases when changes are being added. This is to denote
+ that this code is <emphasis>not for release</emphasis>. Then
+ as the release nears, the version is bumped according: e.g.
+ <literal>3.0.1 -> 0.0.0 -> 3.0.2</literal>.
+ </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
+ <literal>3.0</literal>, 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. 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>
+ <para>
+ Developers should remember too that if they commit a bugfix to the stable
+ branch, this will more than likely require a separate submission to the
+ main trunk, since these are separate development trees within CVS. If you
+ are working on both, then this would require at least two separate check
+ outs (i.e main trunk, <emphasis>and</emphasis> the stable release branch,
+ which is <literal>v_3_0_branch</literal> at the moment).
+ </para>
</sect2>
<listitem>
<para>
Increment the version number (point from odd to even in development
- branches!) in <filename>configure.in</filename>.
+ branches!) in <filename>configure.in</filename>. (RPM spec files
+ will need to be incremented as well.)
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- If the HTML documentation is not in sync with the SGML sources
- you need to regenerate and upload it to the webserver. (If in
- doubt, just do it.) See the Section "Updating the webserver" in
- this manual for details.
+ All documentation should be rebuild after the version bump.
+ Finished docs should be then be committed to CVS (for those
+ without the ability to build these). Some docs may require
+ rather obscure processing tools. <filename>config</filename>,
+ the man page (and the html version of the man page), and the PDF docs
+ fall in this category. REAMDE, the man page, AUTHORS, and config
+ should all also be committed to CVS for other packagers. The
+ formal docs should be uploaded to the webserver. See the
+ Section "Updating the webserver" in this manual for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <citetitle>User Manual</citetitle> is also used for context
+ sensitive help for the CGI editor. This is version sensitive, so that
+ the user will get appropriate help for his/her release. So with
+ each release a fresh version should be uploaded to the webserver
+ (this is in addition to the main <citetitle>User Manual</citetitle>
+ link from the main page since we need to keep manuals for various
+ versions available). The CGI pages will link to something like
+ <literal>http://privoxy.org/$(VERSION)/user-manual/</literal>. This
+ will need to be updated for each new release. There is no Makefile
+ target for this at this time!!! It needs to be done manually.
</para>
</listitem>
+ <listitem>
+ <para>
+ All developers should look at the <filename>ChangeLog</filename> and
+ make sure noteworthy changes are referenced.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>Commit all files that were changed in the above steps!</emphasis>
<para>
For <emphasis>all</emphasis> types of packages, including the source tarball,
<emphasis>you must make sure that you build from clean sources by exporting
- the right version from CVS into an empty directory:</emphasis>.
+ the right version from CVS into an empty directory</emphasis> (just press return when
+ asked for a password):
</para>
<para>
maintainers to do this if you can't).
</para>
</listitem>
+ <listitem>
+ <para>
+ Packagers should do a <quote>clean</quote> install of their
+ package after building it. So any previous installs should be
+ removed first to ensure the integrity of the newly built package.
+ Then run the package for a while to make sure there are no
+ obvious problems, before uploading.
+ </para>
+ </listitem>
</itemizedlist>
</para>
mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
include the
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
- location</ulink>, the release notes and the change log.
+ location</ulink>, the release notes and the Changelog. Also, post an
+ updated News item on the project page Sourceforge, and update the Home
+ page and docs linked from the Home page (see below).
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="webserver-update"><title>Update the Webserver</title>
<para>
- When updating the webserver, please follow these steps to make
- sure that no broken links, inconsistent contents or permission
- problems will occur:
+ The webserver should be updated at least with each stable release. When
+ updating, please follow these steps to make sure that no broken links,
+ inconsistent contents or permission problems will occur (as it has many
+ times in the past!):
</para>
<para>
- If you have changed anything in the documentation source SGML files,
- do:
+ If you have changed anything in the stable-branch documentation source
+ SGML files, do:
</para>
<para>
<programlisting>
- make dok # (or make redhat-dok if make dok doesn't work for you)
+ make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
</programlisting>
</para>
<para>
That will generate <filename>doc/webserver/user-manual</filename>,
<filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
+ <filename>doc/webserver/faq</filename>,
+ <filename>doc/pdf/*.pdf</filename> and
<filename>doc/webserver/index.html</filename> automatically.
</para>
<para>
- If you changed the manual page source, generate
+ If you changed the manual page sources, generate
<filename>doc/webserver/man-page/privoxy-man-page.html</filename>
by running <quote><command>make man</command></quote>. (This is
- a separate target due to dependencies on some obscure perl scripts.
- See comments in <filename>GNUmakefile</filename>.)
+ a separate target due to dependencies on some obscure perl scripts
+ [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.)
</para>
<para>
If you want to add new files to the webserver, create them locally in
create new directories under <filename>doc/webserver</filename>).
</para>
<para>
- Next, commit any changes from the above steps to CVS. All set? Then do
+ Next, commit any changes from the above steps to CVS. All set?
+ If these are docs in the stable branch, then do:
</para>
<para>
<programlisting>
</para>
<para>
Please do <emphasis>NOT</emphasis> use any other means of transferring
- files to the webserver to avoid permission problems.
+ files to the webserver to avoid permission problems. Also, please do not
+ upload docs from development branches or versions. The publicly posted
+ docs should be in sync with the last official release.
</para>
</sect1>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
- Revision 1.51 2002/05/29 00:30:59 mal0rd
+ Revision 1.46.2.11 2002/12/11 13:12:15 hal9
+ Rewrite cvs write access give-away section.
+
+ Revision 1.46.2.10 2002/09/26 21:53:45 hal9
+ Changes to reflect recent change in stable branch commit policy (hopefully
+ clearer now).
+
+ Revision 1.46.2.9 2002/09/26 01:21:40 hal9
+ Porting 3.1.1 changes: more on cvs and branches, more on versions and
+ releases.
+
+ 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.
+
+ Revision 1.46.2.6 2002/08/10 11:40:25 oes
+ Added disclaimer about probably being out-of-date and two small hints
+
+ Revision 1.46.2.5 2002/08/09 01:15:12 hal9
+ Added some notes on pre-release steps (test builds first, update ChangeLog).
+
+ Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd
Fixed a little formatting. Clarified debian section.
- Revision 1.50 2002/05/28 04:32:45 hal9
+ Revision 1.46.2.3 2002/05/28 04:32:45 hal9
Change hints on bundling index.html to privoxy-index.html
- Revision 1.49 2002/05/26 17:04:24 hal9
+ Revision 1.46.2.2 2002/05/26 17:04:24 hal9
-Spellcheck, very minor edits, and sync across branches
Revision 1.48 2002/05/26 12:48:31 roro