<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
-<!entity p-version SYSTEM "doc_version.tmp">
-<!entity p-status SYSTEM "doc_status.tmp">
+<!entity p-version "3.0.6">
+<!entity p-status "stable">
<!entity % p-not-stable "IGNORE">
-<!entity % p-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 2.4 2002/09/26 05:57:14 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $
- Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
+ Copyright (C) 2001-2006 Privoxy Developers http://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!
========================================================================
-->
<subscript>
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
- <link linkend="copyright">Copyright</link> &my-copy; 2001, 2002 by
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2006 by
<ulink url="http://www.privoxy.org">Privoxy Developers</ulink>
</subscript>
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 2.4 2002/09/26 05:57:14 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $</pubdate>
<!--
<!-- end boilerplate -->
<para>
- <![%p-stable;[
Please note that this document is constantly evolving. This copy represents
- the state at the release of version &p-version;. ]]>
+ 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:ijbswa-developers@lists.sourceforge.net">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
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>
<ulink url="http://sourceforge.net/docman/?group_id=1">SF's site
documentation</ulink> for the technical access details for your
operating system. For historical reasons, the CVS server is
- called <literal>cvs.ijbswa.sourceforge.net</literal>, the repository is
+ called <literal>ijbswa.cvs.sourceforge.net</literal>, the repository is
called <literal>ijbswa</literal>, and the source tree module is called
<literal>current</literal>.
</para>
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>,
+ url="http://ijbswa.cvs.sourceforge.net/ijbswa/">http://ijbswa.cvs.sourceforge.net/ijbswa/</ulink>,
which might help with visualizing how these pieces fit together.
</para>
<para>
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).
- And for testing bugfixes for the stable series. 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
+ 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>
+ At one time there were two distinct branches: stable and unstable. The
+ more drastic changes were to be in the unstable branch. These branches
+ have now been merged to minimize time and effort of maintaining two
+ branches.
+ </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
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>
<itemizedlist>
<listitem><para>
- Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
- that small change without testing it thoroughly first. When we're
+ Please don't commit even
+ a small change without testing it thoroughly first. When we're
close to a public release, ask a fellow developer to review your
changes.
</para></listitem>
</itemizedlist>
</para>
+<!--
<para>
- Stable branches are handled with decidedly 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):
+ 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>
</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 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>
- <listitem><para>
- ..a new feature that can be turned off: shoot
- </para></listitem>
- <listitem><para>
- ..a clear improvement w/o side effects on other parts of the code: shoot
- </para></listitem>
- <listitem><para>
- ..a matter of taste: <ulink url="mailto:developers@privoxy.org">ask the list</ulink>
- </para></listitem>
- <listitem><para>
- ..a major redesign of some part of the code: <ulink url="mailto:developers@privoxy.org">ask
- the list</ulink>
- </para></listitem>
- </orderedlist>
- </para>
- <para>
- Note that near a major public release, we get a bit more cautious - if
- unsure, it doesn't hurt to ask first. There is always the possibility
- to submit a patch to the <ulink
- url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patches
- tracker</ulink> instead.
- </para>
- </sect2>
- -->
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
<ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
course this, the <citetitle>developer-manual</citetitle> in this format.
- The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
+ The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>,
+ <citetitle>INSTALL</citetitle>,
<citetitle>privoxy.1</citetitle> (man page), and
<citetitle>config</citetitle> files are also now maintained as Docbook
SGML. These files, when built, in the top-level source directory are
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 Hal).
+ contact someone involved in the documentation.
</para>
<para>
<filename>config</filename> requires some special handling. The reason it
<filename>config</filename>.
</para>
<para>
- Other, less formal documents (e.g. <filename>LICENSE</filename>,
- <filename>INSTALL</filename>) are maintained as plain text files in the
- top-level source directory. At least for the time being.
+ Other, less formal documents (e.g. <filename>LICENSE</filename>) are
+ maintained as plain text files in the top-level source directory.
</para>
<para>
Packagers are encouraged to include this documentation. For those without
the ability to build the docs locally, text versions of each are kept in
- CVS. HTML versions are also now being kept in CVS under
- <filename>doc/webserver/*</filename>.
+ CVS. HTML versions are also being kept in CVS under
+ <filename>doc/webserver/*</filename>. And PDF version are kept in
+ <filename>doc/pdf/*</filename>.
</para>
<para>
Formal documents are built with the Makefile targets of
<para>
You might also find <quote><ulink
- url="http://www.bureau-cornavin.com/opensource/crash-course/">Writing Documentation
+ url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation
Using DocBook - A Crash Course</ulink></quote> useful.
</para>
</sect2>
<listitem>
<para>
Our documents are available in differing formats. Right now, they
- are just plain text, TML, and PDF, but others are always a
+ are just plain text, HTML, 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 2.4 2002/09/26 05:57:14 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge
* Privoxy team. http://www.privoxy.org/
*
* Based on the Internet Junkbuster originally written
* The GNU General Public License should be included with
* this file. If not, you can view it at
* http://www.gnu.org/copyleft/gpl.html
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
* Revisions :
* $L<!-- Break CVS Substitution -->og$
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.4 2002/09/26 05:57:14 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge
* Privoxy team. http://www.privoxy.org/
*
* Based on the Internet Junkbuster originally written
* The GNU General Public License should be included with
* this file. If not, you can view it at
* http://www.gnu.org/copyleft/gpl.html
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
* Revisions :
* $L<!-- Break CVS Substitution -->og$
<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 (e.g. <literal>3.0.0</literal>), where:
+ separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
<itemizedlist>
<listitem>
<para>
<programlisting>
mkdir dist # delete or choose different name if it already exists
cd dist
- cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
</programlisting>
</para>
on exactly the same code.
</para>
+ <warning>
+ <para>
+ Every significant release of Privoxy has included at least one
+ package that either had incorrect versions of files, missing files,
+ or incidental leftovers from a previous build process that gave
+ unknown numbers of users headaches to try to figure out what was
+ wrong. PLEASE, make sure you are using pristene sources, and are
+ following the prescribed process!
+ </para>
+ </warning>
+
<para>
Please find additional instructions for the source tarball and the
individual platform dependent binary packages below. And details
</listitem>
<listitem>
<para>
- <filename>user.action</filename> is designed for local preferences.
- Make sure this does not get overwritten!
+ <filename>user.action</filename> and <filename>user.filter</filename>
+ are designed for local preferences. Make sure these do not get overwritten!
+ <filename>config</filename> should not be overwritten either. This
+ has especially important configuration data in it.
+ <filename>trust</filename> should be left in tact as well.
</para>
</listitem>
<listitem>
<para>
- Other configuration files should be installed as the new defaults,
- but all previously installed configuration files should be preserved
- as backups. This is just good manners :-)
+ Other configuration files (<filename>default.action</filename>,
+ <filename>default.filter</filename> and
+ <filename>standard.action</filename>) should be installed as the new
+ defaults, but all previously installed configuration files should be
+ preserved as backups. This is just good manners :-) These files are
+ likely to change between releases and contain important new features
+ and bug fixes.
</para>
</listitem>
<listitem>
</para>
<para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
</programlisting>
</para>
<para>
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
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).
+ page and docs linked from the Home page (see below). Other news sites
+ and release oriented sites, such as Freshmeat, should also be notified.
</para>
</sect2>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
- Revision 2.4 2002/09/26 05:57:14 hal9
- Conditionally exclude 'this doc is evolving' comment in intro for non release
- situations.
-
- Revision 2.3 2002/09/05 02:27:59 hal9
- Mention tested stable branch fixes in main trunk, as alternate to posting
- patches.
-
- Revision 2.2 2002/09/04 01:55:44 hal9
- Migrating developer manual, and related sgml files from 3.0. Add additional
- commentary on cvs, versioning, stable branches, and how to handle stable
- branches in cvs.
+ Revision 2.11 2006/09/26 02:36:29 hal9
+ Fix broken link per bug tracker.
+
+ Revision 2.10 2006/09/22 01:27:55 hal9
+ Final commit of probably various minor changes here and there. Unless
+ something changes this should be ready for pending release.
+
+ Revision 2.9 2006/09/14 02:30:07 hal9
+ Fix ijbswa cvs links. Update notes on release process, and which config files
+ should be overwritten and which not.
+
+ Revision 2.8 2006/08/22 23:35:01 hal9
+ Fix email address, cvs URI, address branching changes and various other
+ small updates.
+
+ Revision 2.7 2006/07/18 14:48:50 david__schmidt
+ Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch)
+ with what was really the latest development (the v_3_0_branch branch)
+
+ 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
projects / privoxy.git / blobdiff