<!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.10">
+<!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.1 2002/07/29 22:08:40 jongfoster 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.46.2.8 2002/08/17 00:16:10 hal9 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: -->
-->
<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
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>
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>
<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 more care, especially after the
initial *.*.0 release, and we are just in bugfix mode. In addition to
the above, the below applies only to the stable branch (currently the
- v_3_0_branchpoint branch):
+ <literal>v_3_0_branch</literal> branch):
</para>
<para>
<itemizedlist>
- <listitem><para>
- Do <emphasis>not commit anything</emphasis> into the stable branch,
- unless immediately before a new release! There needs to be testing
- done before it hits CVS, and to ensure that all changes are
- appropriate just to fix whatever the problem is.
- </para></listitem>
- <listitem>
- <para>
- Submit any proposed changes as patches first to the patch tracker on
- Sourceforge: <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=311118">http://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
- Then ask for peer review.
- </para>
- </listitem>
<listitem>
<para>
- Do not commit <emphasis>anything</emphasis> unless your patches
- been well tested first, by other members of the project,
- and has prior approval of the project leaders or consensus of the
- devel list.
+ 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!
</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>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.8 2002/08/17 00:16:10 hal9 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.8 2002/08/17 00:16:10 hal9 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$
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>
In summary, the main CVS trunk is the development branch where new
features are being worked on for the next stable series. This should
almost always be where the most activity takes place. There is always at
- least one stable branch from the trunk, e.g now it is 3.0, which is only
- used to release stable versions. Once the initial .0 release of the
- stable branch has been done, then as a rule, only bugfixes that have had
- prior testing should be committed to the stable branch. At that point, it
- is mostly <quote>hands off</quote>. Once there are enough bugfixes to
- justify a new release, the version of this branch is again incremented
- Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable releases from within
- the stable branch. 3.1.x is currently the main trunk, and where work on
- 3.2.x is taking place. If any questions, please post to the devel list
+ 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>
<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>
</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
<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.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).
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