<!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-version SYSTEM "doc_version.tmp">
+<!entity p-status SYSTEM "doc_status.tmp">
+<!entity % p-not-stable "IGNORE">
<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 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. You have been warned!
- Failure to abide by this rule will result in the revocation of your license
- to live a peaceful existence!
+ anything in this, or other Privoxy documentation.
========================================================================
-->
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $</pubdate>
<!--
-->
+<abstract>
<![%dummy;[
<para>
</para>
]]>
<para>
- The developer manual gives the users information on how to help the developer
- team. It provides guidance on coding, testing, documentation and other
- issues.
- </para>
+ The developer manual provides guidance on coding, testing, packaging, documentation
+ and other issues of importance to those involved with
+ <application>Privoxy</application> development. It is mandatory (and helpful!) reading
+ for anyone who wants to join the team.
+</para>
<!-- Include privoxy.sgml boilerplate text: -->
</para></listitem>
<listitem><para>
If your changes span multiple files, and the code won't recompile unless
- all changes are commited (e.g. when changing the signature of a function),
- then commit all files one after another, without long delays in beween.
+ all changes are committed (e.g. when changing the signature of a function),
+ then commit all files one after another, without long delays in between.
If necessary, prepare the commit messages in advance.
</para></listitem>
<listitem><para>
We don't have a too formal policy on this, just use common sense. Hints: If it is..
<orderedlist numeration="arabic">
<listitem><para>
- ..a bugfix / clean-up / cosmetic thing: shoot
+ ..a bug-fix / clean-up / cosmetic thing: shoot
</para></listitem>
<listitem><para>
..a new feature that can be turned off: shoot
<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>
- <citetitle>privoxy.1</citetitle> (man page) files are also now maintained
- as Docbook SGML. The finished files are all in the top-level source
- directory are generated files! Also, <filename>index.html</filename>, the
- <application>Privoxy</application> home page, is maintained as SGML.
+ <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
+ generated files! Also, the <application>Privoxy</application> <filename>index.html</filename> (and a
+ 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).
</para>
+ <para>
+ <filename>config</filename> requires some special handling. The reason it
+ is maintained this way is so that the extensive comments in the file
+ mirror those in <citetitle>user-manual</citetitle>. But the conversion
+ process requires going from SGML to HTML to text to special formatting
+ required for the embedded comments. Some of this does not survive so
+ well. Especially some of the examples that are longer than 80 characters.
+ The build process for this file outputs to <filename>config.new</filename>,
+ 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>,
<filename>INSTALL</filename>) are maintained as plain text files in the
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accommodate this.</para>
+ free/unload/destructor type function to accommodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 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.43 2002/05/10 01:48:19 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
intelligent (keep it short and precise).</para>
</listitem>
</itemizedlist>
- Do not mail to the mailinglist (we cannot keep track on issues there).
+ Do not mail to the mailing list (we cannot keep track on issues there).
</para>
</sect2>
Y, the version minor, represents the branch within the major version.
At any point in time, there are two branches being maintained:
The stable branch, with an even minor, say, 2N, in which no functionality is
- being added and only bugfixes are made, and 2N+1, the development branch, in
+ being added and only bug-fixes are made, and 2N+1, the development branch, in
which the further development of <application>Privoxy</application> takes
place.
This enables us to turn the code upside down and inside out, while at the same time
providing and maintaining a stable version.
- The minor is reset to zero (and one) when the major is inrcemented. When a development
+ The minor is reset to zero (and one) when the major is incremented. When a development
branch has matured to the point where it can be turned into stable, the old stable branch
2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
new stable branch 2N+2, and a new development branch 2N+3 is opened.
on the Sourceforge release process below that.
</para>
+ <sect3 id="pack-guidelines">
+ <title>Note on Privoxy Packaging</title>
+ <para>
+ Please keep these general guidelines in mind when putting together
+ your package. These apply to <emphasis>all</emphasis> platforms!
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <application>Privoxy</application> <emphasis>requires</emphasis>
+ write access to: all <filename>*.action</filename> files, all
+ logfiles, and the <filename>trust</filename> file. You will
+ need to determine the best way to do this for your platform.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Please include up to date documentation. At a bare minimum:
+ </para>
+ <simplelist>
+ <member>
+ <filename>LICENSE</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>README</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>AUTHORS</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>man page</filename> (top-level directory, Unix-like
+ platforms only)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>The User Manual</filename> (doc/webserver/user-manual/)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>FAQ</filename> (doc/webserver/faq/)
+ </member>
+ </simplelist>
+ <para>
+ Also suggested: <filename>Developer Manual</filename>
+ (doc/webserver/developer-manual) and <filename>ChangeLog</filename>
+ (top-level directory). <filename>FAQ</filename> and the manuals are
+ HTML docs. There are also text versions in
+ <filename>doc/text/</filename> which could conceivably also be
+ included.
+ </para>
+ <para>
+ The documentation has been designed such that the manuals are linked
+ to each other from parallel directories, and should be packaged
+ that way. <filename>privoxy-index.html</filename> can also be
+ included and can serve as a focal point for docs and other links of
+ interest (and possibly renamed to <filename>index.html</filename>).
+ This should be one level up from the manuals. There is a link also
+ on this page to an HTMLized version of the man page. To avoid 404 for
+ this, it is in CVS as
+ <filename>doc/webserver/man-page/privoxy-man-page.html</filename>,
+ and should be included along with the manuals. There is also a
+ css stylesheets that can be included for better presentation:
+ <filename>p_doc.css</filename>. This should be in the same directory
+ with <filename>privoxy-index.html</filename>, (i.e. one level up from
+ the manual directories).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>user.action</filename> is designed for local preferences.
+ Make sure this does not get overwritten!
+ </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 :-)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Please check platform specific notes in this doc, if you haven't
+ done <quote>Privoxy</quote> packaging before for other platform
+ specific issues. Conversely, please add any notes that you know
+ are important for your platform (or contact one of the doc
+ maintainers to do this if you can't).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </sect3>
+
<sect3 id="newrelease-tarball"><title>Source Tarball</title>
<para>
First, <emphasis>make sure that you have freshly exported the right
</para>
<para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd winsetup
- make
+ cd winsetup
+ make
</programlisting>
</para>
<para>
<sect3 id="newrelease-debian"><title>Debian</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then, run:
- </para>
- <para>
- <programlisting>
- cd current
- autoheader && autoconf && ./configure
+ First, <emphasis>make sure that you have freshly exported the
+ right version into an empty directory</emphasis>. (See
+ "Building and releasing packages" above). Then add a log
+ entry to <filename>debian/changelog</filename>, if it is not
+ already there, for example by running:
+ </para>
+ <para>
+ <programlisting>
+ debchange -v &p-version;-&p-status;-1 "New upstream version"
</programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
+ </para>
+ <para>
+ Then, run:
+ </para>
+ <para>
+ <programlisting>
+ dpkg-buildpackage -rfakeroot -us -uc -b
+</programlisting>
+ </para>
+ <para>
+ This will create
+ <filename>../privoxy_&p-version;-&p-status;-1_i386.deb</filename>
+ which can be uploaded. To upload the package to Sourceforge, simply
+ issue
+ </para>
+ <para>
+ <programlisting>
+ make debian-upload
+</programlisting>
+ </para>
</sect3>
<sect3 id="newrelease-macosx"><title>Mac OSX</title>
</para>
<para>
<programlisting>
-zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
+ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
</programlisting>
</para>
<para>
<sect3 id="newrelease-freebsd"><title>FreeBSD</title>
<para>
- Login to Sourceforge's compilefarm via ssh:
+ Login to Sourceforge's compile-farm via ssh:
</para>
<para>
<programlisting>
<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, incosistent contents or permission
+ sure that no broken links, inconsistent contents or permission
problems will occur:
</para>
<para>
</para>
<para>
<programlisting>
- make dok # (or make redkat-dok if make dok doesn't work for you)
+ make dok # (or make redhat-dok if make dok doesn't work for you)
</programlisting>
</para>
<para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.50 2002/06/05 00:31:55 hal9
+ Mass commit for new entities, most significantly so docs can read version
+ and code status info from tmp files, so perl is no longer used. Also, docs can
+ differentiate on alpha -> beta -> stable now.
+
+ Revision 1.49 2002/06/03 00:28:16 hal9
+ Sync with various changes from 3.0 branch. Add two new files for config stuff.
+
+ Revision 1.51 2002/05/29 00:30:59 mal0rd
+ Fixed a little formatting. Clarified debian section.
+
+ Revision 1.50 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
+ -Spellcheck, very minor edits, and sync across branches
+
+ Revision 1.48 2002/05/26 12:48:31 roro
+ Add releasing information about Debian.
+
+ Revision 1.47 2002/05/26 04:55:11 mal0rd
+ Added debian-dist and debian-upload targets. Also documented usage.
+
+ Revision 1.46 2002/05/22 17:15:00 oes
+ Updated intro
+
+ Revision 1.45 2002/05/19 23:01:54 hal9
+ Add small section on general packaging guidelines (e.g. actions files must
+ be writable).
+
+ Revision 1.44 2002/05/15 03:55:17 hal9
+ Fix ulink -> link, and minor modification to release process section for
+ clarification.
+
Revision 1.43 2002/05/10 01:48:19 hal9
This is mostly proposed copyright/licensing additions and changes. Docs
are still GPL, but licensing and copyright are more visible. Also, copyright
projects / privoxy.git / blobdiff