<!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.10">
+<!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 2.20 2008/06/14 13:21:24 fabiankeil Exp $
- Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
+ Copyright (C) 2001-2008 Privoxy Developers http://www.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
- <ulink url="http://www.privoxy.org">Privoxy Developers</ulink>
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2008 by
+ <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.51 2002/05/29 00:30:59 mal0rd Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 fabiankeil Exp $</pubdate>
<!--
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.
+ for anyone who wants to join the team. Note that it's currently out of date
+ and may not be entirely correct. As always, patches are welcome.
</para>
<!-- Include privoxy.sgml boilerplate text: -->
<!-- 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>
-->
<para>
<application>Privoxy</application>, as an heir to
- <application>Junkbuster</application>, is an Open Source project
- and licensed under the GPL. As such, <application>Privoxy</application>
- development is potentially open to anyone who has the time, knowledge,
- and desire to contribute in any capacity. Our goals are simply to
- continue the mission, to improve <application>Privoxy</application>, and
+ <application>Junkbuster</application>, is a Free Software project
+ and the code is licensed under the GNU General Public License version 2.
+ As such, <application>Privoxy</application> development is potentially open
+ to anyone who has the time, knowledge, and desire to contribute
+ in any capacity. Our goals are simply to continue the mission,
+ to improve <application>Privoxy</application>, and
to make it available to as wide an audience as possible.
</para>
<para>
One does not have to be a programmer to contribute. Packaging, testing,
- and porting, are all important jobs as well.
+ documenting and porting, are all important jobs as well.
</para>
<!-- ~~~~~ 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
+ 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>
<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>
</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://ijbswa.cvs.sourceforge.net/ijbswa/">http://ijbswa.cvs.sourceforge.net/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>
+ 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
+ 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
- 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>
</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>
- </sect2>
-
- <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">
- <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>
+ 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>
- 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>
+ <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>
+
</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 Stefan and
- Hal).
+ contact someone involved in the documentation.
</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>,
- <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
<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
<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, and HTML, but PDF, and others is 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>Explanation:</emphasis></para>
<para>Comment as much as possible without commenting the obvious.
- For example do not comment "aVariable is equal to bVariable".
- Instead explain why aVariable should be equal to the bVariable.
+ For example do not comment "variable_a is equal to variable_b".
+ Instead explain why variable_a should be equal to the variable_b.
Just because a person can read code does not mean they will
understand why or what is being done. A reader may spend a lot
more time figuring out what is going on when a simple comment
<para><emphasis>Example:</emphasis></para>
<programlisting>
/* if page size greater than 1k ... */
-if ( PageLength() > 1024 )
+if ( page_length() > 1024 )
{
... "block" the page up ...
}
/* if page size is small, send it in blocks */
-if ( PageLength() > 1024 )
+if ( page_length() > 1024 )
{
... "block" the page up ...
}
/*********************************************************************
* This will stand out clearly in your code!
*********************************************************************/
-if ( thisVariable == thatVariable )
+if ( this_variable == that_variable )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
/* unfortunately, this may not */
-if ( thisVariable == thatVariable )
+if ( this_variable == that_variable )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
-if ( thisVariable == thatVariable ) /* this may not either */
+if ( this_variable == that_variable ) /* this may not either */
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}</programlisting>
<para><emphasis>Exception:</emphasis></para>
* This will stand out clearly in your code,
* But the second example won't.
*********************************************************************/
-if ( thisVariable == thatVariable )
+if ( this_variable == this_variable )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
-if ( thisVariable == thatVariable ) /*can you see me?*/
+if ( this_variable == this_variable ) /*can you see me?*/
{
- DoSomethingVeryImportant(); /*not easily*/
+ do_something_very_important(); /*not easily*/
}
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
-short DoSomethingVeryImportant(
+short do_something_very_important(
short firstparam, /* represents something */
short nextparam /* represents something else */ )
{
...code here...
-} /* -END- DoSomethingVeryImportant */
+} /* -END- do_something_very_important */
</programlisting>
</sect3>
<programlisting>
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */
</programlisting>
<programlisting>
if ( this == that )
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
}</programlisting>
<para><emphasis>Instead of:</emphasis></para>
- <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
+ <para>if ( this == that ) do_something(); do_something_else();</para>
<para>or</para>
- <para>if ( this == that ) DoSomething();</para>
+ <para>if ( this == that ) do_something();</para>
<para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
in a manner other than that which the developer desired (per
<para><emphasis>Example:</emphasis></para>
<programlisting>
-int firstValue = 0;
-int someValue = 0;
-int anotherValue = 0;
-int thisVariable = 0;
+int first_value = 0;
+int some_value = 0;
+int another_value = 0;
+int this_variable = 0;
-if ( thisVariable == thatVariable )
+if ( this_variable == this_variable )
-firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
+first_value = old_value + ( ( some_value - another_value ) - whatever )
</programlisting>
</sect3>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-aStruct->aMember;
-aStruct.aMember;
-FunctionName();</programlisting>
+a_struct->a_member;
+a_struct.a_member;
+function_name();</programlisting>
- <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
- FunctionName ();</para>
+ <para><emphasis>Instead of:</emphasis> a_struct -> a_member; a_struct . a_member;
+ function_name ();</para>
</sect3>
int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
<para><emphasis>Instead of:</emphasis></para>
- <para>int function1( ... ) { ...code... return( retCode ); } int
+ <para>int function1( ... ) { ...code... return( ret_code ); } int
function2( ... ) { }</para>
<para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
<para><emphasis>Example:</emphasis></para>
<programlisting>
-short anShort = 0;
-float aFloat = 0;
+short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;</programlisting>
<para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
message says you are trying to access memory address 00000000
- and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
- arrayPtr[0].</para>
+ and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
+ array_ptr[0].</para>
<para><emphasis>Status:</emphasis> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();
+should_we_block_this();
+contains_an_image();
+is_web_page_blank();
</programlisting>
</sect3>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}</programlisting>
each and every iteration. This increases the overhead in the
program, because the compiler has to look up the function each
time, call it, and return a value. Depending on what occurs in
- the blockListLength() call, it might even be creating and
+ the block_list_length() call, it might even be creating and
destroying structures with each iteration, even though in each
case it is comparing "cnt" to the same value, over and over.
- Remember too - even a call to blockListLength() is a function
+ Remember too - even a call to block_list_length() is a function
call, with the same overhead.</para>
<para>Instead of using a function call during the iterations,
<para><emphasis>Example:</emphasis></para>
<programlisting>
-size_t len = blockListLength();
+size_t len = block_list_length();
-for ( size_t cnt = 0; cnt < len; cnt ++ )
+for ( size_t cnt = 0; cnt < len; cnt++ )
{
....
}</programlisting>
- <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
- change or could *potentially* change, then you must code the
+ <para><emphasis>Exceptions:</emphasis> if the value of block_list_length()
+ *may* change or could *potentially* change, then you must code the
function call in the for/while loop.</para>
<para><emphasis>Another Note:</emphasis> This is not so much a readability issue
as a robust programming issue. The "anomaly code goes here" may
be no more than a print to the STDERR stream (as in
- load_config). Or it may really be an ABEND condition.</para>
+ load_config). Or it may really be an abort condition.</para>
<para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
assumptions about whether it is signed or unsigned, or about
how long it is. Do not compare a size_t against another
variable of a different type (or even against a constant)
- without casting one of the values. Try to avoid using size_t if
- you can.</para>
+ without casting one of the values.</para>
</sect3>
<para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
variables or other trivial variables; feel free to declare them
- on 1 line. You should, although, provide a good comment on
+ on one line. You should, although, provide a good comment on
their functions.</para>
<para><emphasis>Status:</emphasis> developer-discretion.</para>
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- existing code, use FIXME</title>
+ existing code, use FIXME or XXX</title>
<para><emphasis>Explanation:</emphasis></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 2.20 2008/06/14 13:21:24 fabiankeil 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-2007 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 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 fabiankeil 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-2007 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, 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>
<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>
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>
</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>
</sect3>
- <sect3 id="newrelease-macosx"><title>Mac OSX</title>
+ <sect3 id="newrelease-macosx"><title>Mac OS X</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 get the Mac OSX setup module:
+ packages" above). Then get the Mac OS X setup module:
</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>
Or use the <command>make</command> targets as described above.
</para>
<para>
- Once this done go to <ulink url="http://sourceforge.net/project/admin/editpackages.php?group_id=11118">http://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
+ Once this done go to <ulink
+ url="https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
+ >https://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
making sure you are logged in. Find your target platform in the
second column, and click <literal>Add Release</literal>. You will
then need to create a new release for your package, using the format
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). Other news sites
+ and release oriented sites, such as Freshmeat, should also be notified.
</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 2.20 2008/06/14 13:21:24 fabiankeil
+ Prepare for the upcoming 3.0.9 beta release.
+
+ Revision 2.19 2008/05/12 11:13:33 fabiankeil
+ Clarify that Privoxy is licensed under GPL version 2.
+
+ Revision 2.18 2008/02/04 12:14:06 fabiankeil
+ Change "Edit Packages" URL to use https.
+
+ Revision 2.17 2008/02/03 21:37:41 hal9
+ Apply patch from Mark: s/OSX/OS X/
+
+ Revision 2.16 2008/01/19 17:52:38 hal9
+ Re-commit to fix various minor issues for new release.
+
+ Revision 2.15 2008/01/19 15:03:05 hal9
+ Doc sources tagged for 3.0.8 release.
+
+ Revision 2.14 2008/01/17 01:49:51 hal9
+ Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon
+ enough.
+
+ Revision 2.13 2007/10/30 17:59:31 fabiankeil
+ - Bump p-version, p-status and copyright date.
+ - Mention that the manual is out of date.
+ - Don't use examples with HardToReadCamelCase after
+ explaining that we actually don't like that.
+ - Minor cosmetics.
+
+ Revision 2.12 2006/11/14 01:57:46 hal9
+ Dump all docs prior to 3.0.6 release. Various minor changes to faq and user
+ manual.
+
+ 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
+ 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
More boilerplate text for use across multiple docs.
Revision 1.20 2002/04/04 03:28:27 david__schmidt
- Add Mac OSX section
+ Add Mac OS X section
Revision 1.19 2002/04/03 15:09:42 david__schmidt
Add OS/2 build section
projects / privoxy.git / blobdiff