<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
-<!entity % dummy "INCLUDE">
+<!entity % dummy "IGNORE">
<!entity supported SYSTEM "supported.sgml">
<!entity newfeatures SYSTEM "newfeatures.sgml">
<!entity p-intro SYSTEM "privoxy.sgml">
<!entity history SYSTEM "history.sgml">
<!entity seealso SYSTEM "seealso.sgml">
-<!entity contacting SYSTEM "contacting.sgml">
-<!entity copyright SYSTEM "copyright.sgml">
-<!entity p-version "2.9.13">
+<!entity p-version "3.0.25">
<!entity p-status "beta">
<!entity % p-not-stable "INCLUDE">
<!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 -->
+<!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml -->
+<!entity my-copy "©"> <!-- kludge for docbook2man -->
]>
<!--
File : $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
Purpose : developer manual
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
-
- $Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $
- Written by and Copyright (C) 2001 the SourceForge
- Privoxy team. http://www.privoxy.org/
-
- Based on the Internet Junkbuster originally written
- by and Copyright (C) 1997 Anonymous Coders and
- Junkbusters Corporation. http://www.junkbusters.com
+ $Id: developer-manual.sgml,v 2.70 2016/05/22 12:42:11 fabiankeil Exp $
+ Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
+ See LICENSE.
========================================================================
- NOTE: Please read developer-manual/documentation.html before touching
+ 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
+ Failure to abide by this rule will result in the revocation of your license
to live a peaceful existence!
========================================================================
<article id="index">
<artheader>
<title>Privoxy Developer Manual</title>
+ <pubdate>
+ <subscript>
+ <!-- Completely the wrong markup, but very little is allowed -->
+ <!-- in this part of an article. FIXME -->
+ <ulink url="https://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
+ &my-copy; 2001-2016 by
+ <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
+ </subscript>
+ </pubdate>
+
+
+ <pubdate>$Id: developer-manual.sgml,v 2.70 2016/05/22 12:42:11 fabiankeil Exp $</pubdate>
+
+<!--
+
+Note: this should generate a separate page, and a live link to it.
+But it doesn't for some mysterious reason. Please leave commented
+unless it can be fixed proper. For the time being, the copyright
+statement will be in copyright.smgl.
- <pubdate>$Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $</pubdate>
+Hal.
+
+<legalnotice id="legalnotice">
+ <para>
+ text goes here ........
+ </para>
+</legalnotice>
- <authorgroup>
- <author>
- <affiliation>
- <orgname>By: Privoxy Developers</orgname>
- </affiliation>
- </author>
- </authorgroup>
+-->
<abstract>
+
<![%dummy;[
<para>
<comment>
</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. 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: -->
- &p-intro;
+<!-- &p-intro; Someone interested enough in the project to contribute
+ will already know at this point what Privoxy is. -->
<!-- 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 the Contact section on how to contact the developers.
+ url="https://www.privoxy.org/developer-manual/">https://www.privoxy.org/developer-manual/</ulink>.
+ Please have a look at the
+ <ulink url="https://www.privoxy.org/user-manual/contact.html">contact section in the user manual</ulink>
+ if you are interested in contacting the developers.
</para>
-<!-- <para> -->
-<!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
-<!-- </para> -->
-
</abstract>
</artheader>
-<!-- ~~~~~ New section ~~~~~ -->
-<sect1 id="intro" label=""><title></title>
-<!-- dummy section to force TOC on page by itself -->
-<!-- DO NOT REMOVE! please ;) -->
-<para> </para>
-</sect1>
-
-<!-- ~~~~~ New section ~~~~~ -->
-
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 label="1" id="introduction"><title>Introduction</title>
+ <sect1 id="introduction"><title>Introduction</title>
<!--
I don't like seeing blank space :) So added *something* here.
- -->
+ -->
<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
- to make it available to as wide an audience as possible.
+ <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>
+ The first step is to join the <ulink
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel 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), 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="quickstart"><title>Quickstart to Privoxy Development</title>
+ <sect1 id="cvs"><title>The CVS Repository</title>
<para>
-You'll need an account on <ulink
-url="http://sourceforge.net">Sourceforge</ulink> to support our development.
-Mail your ID to the list and wait until a project manager has added you.
-</para>
+ If you become part of the active development team, you will eventually
+ need write access to our holy grail, the CVS repository. One of the
+ team members will need to set this up for you. Please read
+ this chapter completely before accessing via CVS.
+ </para>
+
+ <sect2 id="cvsaccess"><title>Access to CVS</title>
+ <para>
+ The project's CVS repository is hosted on
+ <ulink url="https://sourceforge.net/">SourceForge.</ulink>
+ For historical reasons, the CVS server 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="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/viewvc/ijbswa/"
+ >http://ijbswa.cvs.sourceforge.net/viewvc/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. <!-- There are differing guidelines for the stable branch and the
+ main development trunk, and --> We expect anyone with CVS access to strictly
+ adhere to the following guidelines:
+ </para>
+
+ <para>
+ Basic Guidelines, for all branches:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem><para>
+ 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>
+ <listitem><para>
+ Your commit message should give a concise overview of <emphasis>what you
+ changed</emphasis> (no big details) and <emphasis>why you changed it</emphasis>
+ Just check previous messages for good examples.
+ </para></listitem>
+ <listitem><para>
+ Don't use the same message on multiple files, unless it equally applies to
+ all those files.
+ </para></listitem>
+ <listitem><para>
+ If your changes span multiple files, and the code won't recompile unless
+ 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>
+ Before changing things on CVS, make sure that your changes are in line
+ 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="https://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch
+ tracker</ulink> instead.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+<!--
+ <para>
+ Stable branches are handled with more care, especially after the
+ initial *.*.0 release, and we are just in bugfix mode. In addition to
+ the above, the below applies only to the stable branch (currently the
+ <literal>v_3_0_branch</literal> branch):
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Do not commit <emphasis>anything</emphasis> unless your proposed
+ changes have been well tested first, preferably by other members of the
+ project, or have prior approval of the project leaders or consensus
+ of the devel list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Where possible, bugfixes and changes should be tested in the main
+ development trunk first. There may be occasions where this is not
+ feasible, though.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Alternately, proposed changes can be submitted as patches to the patch tracker on
+ Sourceforge first: <ulink
+ url="https://sourceforge.net/tracker/?group_id=11118&atid=311118">https://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>
-<para>
-For the time being (read, this section is under construction), please note the
-following guidelines for changing stuff in the code. If it is
- <orderedlist numeration="arabic">
- <listitem><para>
- A bugfix / 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: ask the list
- </para></listitem>
- <listitem><para>
- A major redesign of some part of the code: ask the list
- </para></listitem>
- </orderedlist>
- </para>
-</sect1>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="documentation"><title>Documentation Guidelines</title>
<para>
- All formal documents are maintained in docbook SGML and located in the
+ All formal documents are maintained in Docbook SGML and located in the
<computeroutput>doc/source/*</computeroutput> directory. You will need
- <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
+ <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
and either <application>jade</application> or
<application>openjade</application> (recommended) installed in order to
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>
- <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.
+ 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
+ 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>
+ contact someone involved in the documentation.
+ </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
- toplevel 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
+ CVS. HTML versions are also being kept in CVS under
<filename>doc/webserver/*</filename>.
</para>
<para>
Formal documents are built with the Makefile targets of
- <computeroutput>make dok</computeroutput>, or alternately
- <computeroutput>make redhat-dok</computeroutput>. If you have problems,
- try both. The build process uses the document SGML sources in
+ <computeroutput>make dok</computeroutput>.
+ The build process uses the document SGML sources in
<computeroutput>doc/source/*/*</computeroutput> to update all text files in
<computeroutput>doc/text/</computeroutput> and to update all HTML
documents in <computeroutput>doc/webserver/</computeroutput>.
</para>
<para>
Documentation writers should please make sure documents build
- successfully before committing to CVS.
+ successfully before committing to CVS, if possible.
</para>
<para>
How do you update the webserver (i.e. the pages on privoxy.org)?
-
+
<orderedlist numeration="arabic">
<listitem><para>
First, build the docs by running <computeroutput>make
- dok</computeroutput> (or alternately <computeroutput>make
- redhat-dok</computeroutput>).
+ dok</computeroutput>.
</para></listitem>
<listitem><para>
Run <computeroutput>make webserver</computeroutput> which copies all
</orderedlist>
</para>
+ <para>
+ Finished docs should be occasionally submitted to CVS
+ (<filename>doc/webserver/*/*.html</filename>) so that those without
+ the ability to build them locally, have access to them if needed.
+ This is especially important just prior to a new release! Please
+ do this <emphasis>after</emphasis> the <literal>$VERSION</literal> and
+ other release specific data in <filename>configure.in</filename> has been
+ updated (this is done just prior to a new release).
+ </para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="sgml">
<title>Quickstart to Docbook and SGML</title>
<para>
- If you are not familiar with SGML, it is a markup language similar to HTML.
- Actually, not a mark up language per se, but a language used to define
+ If you are not familiar with SGML, it is a markup language similar to HTML.
+ Actually, not a mark up language per se, but a language used to define
markup languages. In fact, HTML is an SGML application. Both will use
<quote>tags</quote> to format text and other content. SGML tags can be much
more varied, and flexible, but do much of the same kinds of things. The tags,
or <quote>elements</quote>, are definable in SGML. There is no set
<quote>standards</quote>. Since we are using
- <application>Docbook</application>, our tags are those that are defined by
+ <application>Docbook</application>, our tags are those that are defined by
<application>Docbook</application>. Much of how the finish document is
rendered is determined by the <quote>stylesheets</quote>.
The stylesheets determine how each tag gets translated to HTML, or other
<para>
Our documents use <quote>sections</quote> for the most part. Sections
- will be processed into HTML headers (e.g. <literal>h1</literal> for
+ will be processed into HTML headers (e.g. <literal>h1</literal> for
<literal>sect1</literal>). The <application>Docbook</application> stylesheets
- will use these to also generate the Table of Contents for each doc. Our
- TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
- <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
- entries, but <literal>sect4</literal> will not. Each section requires
- a <literal><title></literal> element, and at least one
- <literal><para></literal>. There is a limit of five section
- levels in Docbook, but generally three should be sufficient for our
+ will use these to also generate the Table of Contents for each doc. Our
+ TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
+ <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
+ entries, but <literal>sect4</literal> will not. Each section requires
+ a <literal><title></literal> element, and at least one
+ <literal><para></literal>. There is a limit of five section
+ levels in Docbook, but generally three should be sufficient for our
purposes.
</para>
<para>
- Some common elements that you likely will use:
+ Some common elements that you likely will use:
</para>
-<simplelist>
- <member>
- <emphasis><para></para></emphasis>, paragraph delimiter. Most
- text needs to be within paragraph elements (there are some exceptions).
- </member>
- <member>
- <emphasis><emphasis></emphasis></emphasis>, the stylesheets make this
- italics.
- </member>
- <member>
- <emphasis><filename></filename></emphasis>, files and directories.
- </member>
- <member>
- <emphasis><command></command></emphasis>, command examples.
- </member>
- <member>
- <emphasis><literallayout></literllayout></emphasis>, like
- <literal><pre></literal>, more or less.
- </member>
- <member>
- <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
- </member>
- <member>
- <emphasis><listitem></listitem></emphasis>, member of the above.
- </member>
- <member>
- <emphasis><screen></screen></emphasis>, screen output, implies
- <literal><literallayout></literal>.
- </member>
- <member>
- <emphasis><ulink url="example.com"></ulink></emphasis>, like
- HTML <literal><a></literal> tag.
- </member>
- <member>
- <emphasis><quote></quote></emphasis>, for, doh, quoting text.
- </member>
-</simplelist>
+<para>
+ <simplelist>
+ <member>
+ <emphasis><para></para></emphasis>, paragraph delimiter. Most
+ text needs to be within paragraph elements (there are some exceptions).
+ </member>
+ <member>
+ <emphasis><emphasis></emphasis></emphasis>, the stylesheets
+ make this italics.
+ </member>
+ <member>
+ <emphasis><filename></filename></emphasis>, files and directories.
+ </member>
+ <member>
+ <emphasis><command></command></emphasis>, command examples.
+ </member>
+ <member>
+ <emphasis><literallayout></literallayout></emphasis>, like
+ <literal><pre></literal>, more or less.
+ </member>
+ <member>
+ <emphasis><itemizedlist></itemizedlist></emphasis>, list with bullets.
+ </member>
+ <member>
+ <emphasis><listitem></listitem></emphasis>, member of the above.
+ </member>
+ <member>
+ <emphasis><screen></screen></emphasis>, screen output, implies
+ <literal><literallayout></literal>.
+ </member>
+ <member>
+ <emphasis><ulink url="example.com"></ulink></emphasis>, like
+ HTML <literal><a></literal> tag.
+ </member>
+ <member>
+ <emphasis><quote></quote></emphasis>, for, doh, quoting text.
+ </member>
+ </simplelist>
+</para>
<para>
Look at any of the existing docs for examples of all these and more.
</para>
+<para>
+ You might also find <quote><ulink
+ url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation
+ Using DocBook - A Crash Course</ulink></quote> useful.
+</para>
</sect2>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="docstyle">
<title><application>Privoxy</application> Documentation Style</title>
<para>
- It will be easier if everyone follows a similar writing style. This
- just makes it easier to read what someone else has written if it
+ It will be easier if everyone follows a similar writing style. This
+ just makes it easier to read what someone else has written if it
is all done in a similar fashion.
</para>
<para>
<para>
All tags should be lower case.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
Tags delimiting a <emphasis>block</emphasis> of text (even small
Just to <emphasis>emphasize</emphasis>, some text goes here.
</literallayout>
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
Tags should be nested and step indented for block text like: (except
- in-line tags)
+ in-line tags)
<literallayout>
<para>
<itemizedlist>
</literallayout>
This makes it easier to find the text amongst the tags ;-)
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- Use white space to separate logical divisions within a document,
- like between sections. Running everything together consistently
+ Use white space to separate logical divisions within a document,
+ like between sections. Running everything together consistently
makes it harder to read and work on.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- Do not hesitate to make comments. Comments can either use the
- <comment> element, or the <!-- --> style comment
- familiar from HTML. (Note in Docbook v4.x <comment> is
+ Do not hesitate to make comments. Comments can either use the
+ <comment> element, or the <!-- --> style comment
+ familiar from HTML. (Note in Docbook v4.x <comment> is
replaced by <remark>.)
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- We have an international audience. Refrain from slang, or English
- idiosyncrasies (too many to list :).
+ We have an international audience. Refrain from slang, or English
+ idiosyncrasies (too many to list :). Humor also does not translate
+ well sometimes.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
Try to keep overall line lengths in source files to 80 characters or less
- for obvious reasons. This is not always possible, with lenghty URLs for
+ for obvious reasons. This is not always possible, with lengthy URLs for
instance.
</para>
- </listitem>
+ </listitem>
<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
- future possibility. Be careful with URLs (<ulink>), and avoid
+ Our documents are available in differing formats. Right now, they
+ are just plain text and/or HTML, but others are always a
+ future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</para>
<para>
My favorite site is <ulink url="http://example.com">here</ulink>.
</para>
<para>
- This will render as <quote>My favorite site is here</quote>, which is
+ This will render as <quote>My favorite site is here</quote>, which is
not real helpful in a text doc. Better like this:
</para>
<para>
<literal>-H</literal> option. (<application>ispell</application> I think
too.)
</para>
- </listitem>
+ </listitem>
</itemizedlist>
- </para>
-
+ </para>
+
</sect2>
-
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2><title>Privoxy Custom Entities</title>
<para>
- <application>Privoxy</application> documentation is using
- a number of customized <quote>entities</quote> to facilitate
- documentation maintenance.
+ <application>Privoxy</application> documentation is using
+ a number of customized <quote>entities</quote> to facilitate
+ documentation maintenance.
</para>
<para>
We are using a set of <quote>boilerplate</quote> files with generic text,
that is used by multiple docs. This way we can write something once, and use
it repeatedly without having to re-write the same content over and over again.
If editing such a file, keep in mind that it should be
- <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
+ <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
contexts without additional modifications.
</para>
<para>
- We are also using what <application>Docbook</application> calls
- <quote>internal entities</quote>. These are like variables in
+ We are also using what <application>Docbook</application> calls
+ <quote>internal entities</quote>. These are like variables in
programming. Well, sort of. For instance, we have the
- <literal>p-version</literal> entity that contains the current
- <application>Privoxy</application> version string. You are strongly
- encouraged to use these where possible. Some of these obviously
+ <literal>p-version</literal> entity that contains the current
+ <application>Privoxy</application> version string. You are strongly
+ encouraged to use these where possible. Some of these obviously
require re-setting with each release (done by the Makefile). A sampling of
custom entities are listed below. See any of the main docs for examples.
</para>
<itemizedlist>
<listitem>
<para>
- Re-cyclable <quote>boilerplate</quote> text entities are defined like:
+ Re- <quote>boilerplate</quote> text entities are defined like:
</para>
<para>
<literal><!entity supported SYSTEM "supported.sgml"></literal>
</para>
<para>
In this example, the contents of the file,
- <filename>supported.sgml</filename> is available for inclusion anywhere
- in the doc. To make this happen, just reference the now defined
- entity: <literal>&supported;</literal> (starts with an ampersand
- and ends with a semi-colon), and the contents will be dumped into
+ <filename>supported.sgml</filename> is available for inclusion anywhere
+ in the doc. To make this happen, just reference the now defined
+ entity: <literal>&supported;</literal> (starts with an ampersand
+ and ends with a semi-colon), and the contents will be dumped into
the finished doc at that point.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
Commonly used <quote>internal entities</quote>:
</para>
<simplelist>
<member>
- <emphasis>p-version</emphasis>: the <application>Privoxy</application>
- version string, e.g. <quote>2.9.13</quote>.
+ <emphasis>p-version</emphasis>: the <application>Privoxy</application>
+ version string, e.g. <quote>&p-version;</quote>.
</member>
<member>
- <emphasis>p-status</emphasis>: the project status, either
- <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
+ <emphasis>p-status</emphasis>: the project status, either
+ <quote>alpha</quote>, <quote>beta</quote>, or <quote>stable</quote>.
</member>
<member>
- <emphasis>p-not-stable</emphasis>: use to conditionally include
- text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
+ <emphasis>p-not-stable</emphasis>: use to conditionally include
+ text in <quote>not stable</quote> releases (e.g. <quote>beta</quote>).
</member>
<member>
<emphasis>p-stable</emphasis>: just the opposite.
<emphasis>p-text</emphasis>: this doc is only generated as text.
</member>
</simplelist>
- </listitem>
+ </listitem>
</itemizedlist>
- </para>
+ </para>
<para>
- There are others in various places that are defined for a specific
+ There are others in various places that are defined for a specific
purpose. Read the source!
</para>
-
+
</sect2>
-
+
</sect1>
<!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
</sect2>
<sect2 id="s2"><title>Using Comments</title>
-
+
<sect3 id="s3"><title>Comment, Comment, Comment</title>
<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
or explanation would have prevented the extra research. Please
- help your brother IJB'ers out!</para>
+ help your fellow Privoxy developers out!</para>
<para>The comments will also help justify the intent of the code.
If the comment describes something different than what the code
<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 ...
}
</programlisting>
</sect3>
-
+
<sect3 id="s4"><title>Use blocks for comments</title>
/*********************************************************************
* 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>
<para>If you are trying to add a small logic comment and do not
- wish to "disrubt" the flow of the code, feel free to use a 1
+ wish to "disrupt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.</para>
-
+
</sect3>
-
+
<sect3 id="s5"><title>Keep Comments on their own line</title>
* 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*/
}
int urls_read = 0; /* # of urls read + rejected */
int urls_rejected = 0; /* # of urls rejected */
-if ( 1 == X )
+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>
-
+
<sect3 id="s6"><title>Comment each logical step</title>
comment. After all, these are usually major logic
containers.</para>
-
+
</sect3>
-
+
<sect3 id="s7"><title>Comment All Functions Thoroughly</title>
functions should contain the information presented in the
addendum section of this document.</para>
-
+
</sect3>
-
+
<sect3 id="s8"><title>Comment at the end of braces if the
content is more than one screen length</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-if ( 1 == X )
+if (1 == X)
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
or:
-if ( 1 == X )
+if (1 == X)
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
-} /* -END- if ( 1 == X ) */
+} /* -END- if (1 == X) */
</programlisting>
</sect3>
-
+
</sect2>
<sect2 id="s9"><title>Naming Conventions</title>
-
+
<sect3 id="s10"><title>Variable Names</title>
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
</programlisting>
</para>
-
- </sect3>
+
+ </sect3>
<sect3 id="s11"><title>Function Names</title>
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
<para><emphasis>Example:</emphasis></para>
<programlisting>
-int load_some_file( struct client_state *csp )</programlisting>
+int load_some_file(struct client_state *csp)</programlisting>
<para><emphasis>Instead of:</emphasis></para>
<para>
<programlisting>
-int loadsomefile( struct client_state *csp )
-int loadSomeFile( struct client_state *csp )
+int loadsomefile(struct client_state *csp)
+int loadSomeFile(struct client_state *csp)
</programlisting>
</para>
-
+
</sect3>
-
+
<sect3 id="s12"><title>Header file prototypes</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-(.h) extern int load_aclfile( struct client_state *csp );
-(.c) int load_aclfile( struct client_state *csp )</programlisting>
+(.h) extern int load_aclfile(struct client_state *csp);
+(.c) int load_aclfile(struct client_state *csp)</programlisting>
<para><emphasis>Instead of:</emphasis>
<programlisting>
-(.h) extern int load_aclfile( struct client_state * ); or
-(.h) extern int load_aclfile();
-(.c) int load_aclfile( struct client_state *csp )
+(.h) extern int load_aclfile(struct client_state *); or
+(.h) extern int load_aclfile();
+(.c) int load_aclfile(struct client_state *csp)
</programlisting>
</para>
-
+
</sect3>
-
+
<sect3 id="s13"><title>Enumerations, and #defines</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-(enumeration) : enum Boolean { FALSE, TRUE };
+(enumeration) : enum Boolean {FALSE, TRUE};
(#define) : #define DEFAULT_SIZE 100;</programlisting>
<para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
#endif /* def FEATURE_FORCE */
</programlisting>
</sect3>
-
+
<sect3 id="s14"><title>Constants</title>
<para>
<programlisting>
-#define USE_IMG_LST 1 or
+#define USE_IMG_LST 1 or
#define _USE_IMAGE_LIST 1 or
-#define USE_IMAGE_LIST_ 1 or
+#define USE_IMAGE_LIST_ 1 or
#define use_image_list 1 or
#define UseImageList 1
</programlisting>
</para>
-
+
</sect3>
</sect2>
-
+
<sect2 id="s15"><title>Using Space</title>
-
+
<sect3 id="s16"><title>Put braces on a line by themselves.</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-if ( this == that )
+if (this == that)
{
...
}</programlisting>
<para><emphasis>Instead of:</emphasis></para>
- <para>if ( this == that ) { ... }</para>
+ <para>if (this == that) { ... }</para>
<para>or</para>
- <para>if ( this == that ) { ... }</para>
+ <para>if (this == that) { ... }</para>
<para><emphasis>Note:</emphasis> In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
- condidtion that is obvious from the purpose of the block,
+ condition that is obvious from the purpose of the block,
one-liners as above may optically preserve the loop structure
and make it easier to read.</para>
- <para><emphasis>Status:</emphasis> developer-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
<para><emphasis>Example exception:</emphasis></para>
<programlisting>
-while ( more lines are read )
+while (more lines are read)
{
/* Please document what is/is not a comment line here */
- if ( it's a comment ) continue;
+ if (it's a comment) continue;
- do_something( line );
+ do_something(line);
}
</programlisting>
</sect3>
-
+
<sect3 id="s17"><title>ALL control statements should have a
block</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-if ( this == that )
+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
"feature". The "explanation" and "exception" from the point
above also applies.</para>
-
+
</sect3>
-
+
<sect3 id="s18"><title>Do not belabor/blow-up boolean
expressions</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-structure->flag = ( condition );</programlisting>
+structure->flag = (condition);</programlisting>
<para><emphasis>Instead of:</emphasis></para>
- <para>if ( condition ) { structure->flag = 1; } else {
+ <para>if (condition) { structure->flag = 1; } else {
structure->flag = 0; }</para>
- <para><emphasis>Note:</emphasis> The former is readable and consice. The later
+ <para><emphasis>Note:</emphasis> The former is readable and concise. The later
is wordy and inefficient. Please assume that any developer new
to the project has at least a "good" knowledge of C/C++. (Hope
I do not offend by that last comment ... 8-)</para>
-
+
</sect3>
-
+
<sect3 id="s19"><title>Use white space freely because it is
free</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-int firstValue = 0;
-int someValue = 0;
-int anotherValue = 0;
-int thisVariable = 0;
-
-if ( thisVariable == thatVariable )
-
-firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
+int first_value = 0;
+int some_value = 0;
+int another_value = 0;
+int this_variable = 0;
</programlisting>
</sect3>
-
+
<sect3 id="s20"><title>Don't use white space around structure
operators</title>
<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> a_struct -> a_member; a_struct . a_member;
+ function_name ();</para>
- <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
- FunctionName ();</para>
-
</sect3>
-
+
<sect3 id="s21"><title>Make the last brace of a function stand
out</title>
int function1( ... )
{
...code...
- return( retCode );
+ return(ret_code);
-} /* -END- function1 */
+} /* -END- function1 */
int function2( ... )
{
-} /* -END- function2 */
+} /* -END- function2 */
</programlisting>
<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
- lines afterwards. This makes the end of function standout to
+ lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
- seperate functions, this is still a good coding practice. In
+ separate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!</para>
- <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
+ <para><emphasis>Status:</emphasis> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</para>
-
+
</sect3>
-
+
<sect3 id="s22"><title>Use 3 character indentions</title>
int function1( ... )
{
- if ( 1 )
+ if (1)
{
- return( ALWAYS_TRUE );
+ return ALWAYS_TRUE;
}
else
{
- return( HOW_DID_YOU_GET_HERE );
+ return HOW_DID_YOU_GET_HERE;
}
- return( NEVER_GETS_HERE );
+ return NEVER_GETS_HERE;
}
</programlisting>
</sect3>
</sect2>
-
+
<sect2 id="s23"><title>Initializing</title>
-
+
<sect3 id="s24"><title>Initialize all variables</title>
<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-discrection if and only if the
+ <para><emphasis>Status:</emphasis> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</para>
</sect3>
</sect2>
-
+
<sect2 id="s25"><title>Functions</title>
-
+
<sect3 id="s26"><title>Name functions that return a boolean as a
question.</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();
+should_we_block_this();
+contains_an_image();
+is_web_page_blank();
</programlisting>
</sect3>
-
+
<sect3 id="s27"><title>Always specify a return type for a
function.</title>
purpose, and create a void return type if the function does not
need to return anything.</para>
-
+
</sect3>
-
+
<sect3 id="s28"><title>Minimize function calls when iterating by
using variables</title>
<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>
-
+
</sect3>
-
+
<sect3 id="s29"><title>Pass and Return by Const Reference</title>
<para>This allows a developer to define a const pointer and call
your function. If your function does not have the const
keyword, we may not be able to use your function. Consider
- strcmp, if it were defined as: extern int strcmp( char *s1,
- char *s2 );</para>
+ strcmp, if it were defined as: extern int strcmp(char *s1,
+ char *s2);</para>
- <para>I could then not use it to compare argv's in main: int main(
- int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
- ); }</para>
+ <para>I could then not use it to compare argv's in main: int
+ main(int argc, const char *argv[]) { strcmp(argv[0], "privoxy");
+ }</para>
<para>Both these pointers are *const*! If the c runtime library
maintainers do it, we should too.</para>
-
+
</sect3>
-
+
<sect3 id="s30"><title>Pass and Return by Value</title>
<para>Most structures cannot fit onto a normal stack entry (i.e.
they are not 4 bytes or less). Aka, a function declaration
- like: int load_aclfile( struct client_state csp )</para>
+ like: int load_aclfile(struct client_state csp)</para>
<para>would not work. So, to be consistent, we should declare all
- prototypes with "pass by value": int load_aclfile( struct
- client_state *csp )</para>
+ prototypes with "pass by value": int load_aclfile(struct
+ client_state *csp)</para>
+
-
</sect3>
-
+
<sect3 id="s31"><title>Names of include files</title>
<para>
<programlisting>
-/* This is not a local include, but requires a path element. */
+/* This is not a local include, but requires a path element. */
#include <sys/fileName.h>
</programlisting>
</para>
<para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.</para>
+ "file.h" behavior.</para>
+
-
</sect3>
-
+
<sect3 id="s32"><title>Provide multiple inclusion
protection</title>
#endif /* ndef PROJECT_H_INCLUDED */
</programlisting>
</sect3>
-
+
<sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
#endif /* def __cplusplus */
</programlisting>
</sect3>
-
+
<sect3 id="s34"><title>Where Possible, Use Forward Struct
Declaration Instead of Includes</title>
<para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
pointer), then including the proper header file is necessary.
If you only want to prototype a pointer, however, the header
- file is unneccessary.</para>
+ file is unnecessary.</para>
+
+ <para><emphasis>Status:</emphasis> Use with discretion.</para>
- <para><emphasis>Status:</emphasis> Use with discrection.</para>
-
</sect3>
</sect2>
<sect2 id="s35"><title>General Coding Practices</title>
-
+
<sect3 id="s36"><title>Turn on warnings</title>
should turn on as many as possible. With GCC, the switch is
"-Wall". Try and fix as many warnings as possible.</para>
-
+
</sect3>
-
+
<sect3 id="s37"><title>Provide a default case for all switch
statements</title>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-switch( hash_string( cmd ) )
+switch (hash_string(cmd))
{
- case hash_actions_file :
+ case hash_actions_file:
... code ...
break;
- case hash_confdir :
+ case hash_confdir:
... code ...
break;
- default :
+ default:
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
-} /* end switch( hash_string( cmd ) ) */</programlisting>
+} /* end switch (hash_string(cmd)) */</programlisting>
<para><emphasis>Note:</emphasis> If you already have a default condition, you
are obviously exempt from this point. Of note, most of the
This API call *should* be included in a default statement.</para>
<para><emphasis>Another Note:</emphasis> This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
+ 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>
-
+
</sect3>
-
+
<sect3 id="s38"><title>Try to avoid falling through cases in a
switch statement.</title>
the fact of the fall through and reason why you felt it was
necessary.</para>
-
- </sect3>
-
-
- <sect3 id="s39"><title>Use 'long' or 'short' Instead of
- 'int'</title>
-
- <para><emphasis>Explanation:</emphasis></para>
-
- <para>On 32-bit platforms, int usually has the range of long. On
- 16-bit platforms, int has the range of short.</para>
-
- <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
- projects (including X/GNU-Emacs), there are typedefs to int4,
- int8, int16, (or equivalence ... I forget the exact typedefs
- now). Should we add these to IJB now that we have a "configure"
- script?</para>
-
</sect3>
-
+
<sect3 id="s40"><title>Don't mix size_t and other types</title>
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>
-
+
<sect3 id="s41"><title>Declare each variable and struct on its
own line.</title>
<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-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
+
-
</sect3>
-
+
<sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
<para><emphasis>Explanation:</emphasis></para>
- <para>Create a local stuct (on the stack) if the variable will
+ <para>Create a local struct (on the stack) if the variable will
live and die within the context of one function call.</para>
<para>Only "malloc" a struct (on the heap) if the variable's life
<para><emphasis>Example:</emphasis></para>
<programlisting>
If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.
+list, then it should definitely be allocated via `malloc'.
</programlisting>
</sect3>
-
+
<sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
Responsible for Ensuring 'free'</title>
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 accomodate this.</para>
+ free/unload/destructor type function to accommodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-int load_re_filterfile( struct client_state *csp ) { ... }
-static void unload_re_filterfile( void *f ) { ... }</programlisting>
+int load_re_filterfile(struct client_state *csp) { ... }
+static void unload_re_filterfile(void *f) { ... }</programlisting>
<para><emphasis>Exceptions:</emphasis></para>
functions for C run-time library functions ... such as
`strdup'.</para>
- <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
+ <para><emphasis>Status:</emphasis> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</para>
-
+
</sect3>
-
+
<sect3 id="s44"><title>Add loaders to the `file_list' structure
and in order</title>
POPUPs can also be referred to as KILLPOPUPs, it is clear that
it should come first.</para>
-
+
</sect3>
-
+
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- exitinst code, use FIXME</title>
+ existing code, use XXX</title>
<para><emphasis>Explanation:</emphasis></para>
<para>If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
+ your changes, but are not *quite* sure of the repercussions,
add this:</para>
- <para>/* FIXME: this code has a logic error on platform XYZ, *
- attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ <para>/* XXX: this code has a logic error on platform XYZ, *
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif</para>
<para>or:</para>
- <para>/* FIXME: I think the original author really meant this...
+ <para>/* XXX: I think the original author really meant this...
*/ ...changed code here...</para>
<para>or:</para>
- <para>/* FIXME: new code that *may* break something else... */
+ <para>/* XXX: new code that *may* break something else... */
...new code here...</para>
<para><emphasis>Note:</emphasis> If you make it clear that this may or may not
be a "good thing (tm)", it will be easier to identify and
- include in the project (or conversly exclude from the
+ include in the project (or conversely exclude from the
project).</para>
-
+
</sect3>
</sect2>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $";
+const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
/*********************************************************************
*
- * File : $S<!-- Break CVS Substitution -->ource$
+ * File : $S<!-- Break CVS Substitution -->ource$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
+ * Copyright : Written by and Copyright (C) 2001-2009
+ * the Privoxy team. https://www.privoxy.org/
*
* This program is free software; you can redistribute it
* and/or modify it under the terms of the GNU General
*
* 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.
- *
- * Revisions :
- * $L<!-- Break CVS Substitution -->og$
+ * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
*********************************************************************/
<para><emphasis>Note:</emphasis> The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
- skip the verbige and get to the heart of the code (via
+ skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</para>
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $"
+#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
/*********************************************************************
*
- * File : $S<!-- Break CVS Substitution -->ource$
+ * File : $S<!-- Break CVS Substitution -->ource$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
+ * Copyright : Written by and Copyright (C) 2001-2009
+ * the Privoxy team. https://www.privoxy.org/
*
* This program is free software; you can redistribute it
* and/or modify it under the terms of the GNU General
*
* 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.
- *
- * Revisions :
- * $L<!-- Break CVS Substitution -->og$
+ * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
*********************************************************************/
* Returns : 0 => Ok, everything else is an error.
*
*********************************************************************/
-int FUNCTION_NAME( void *param1, const char *x )
+int FUNCTION_NAME(void *param1, const char *x)
{
...
- return( 0 );
+ return 0;
}
</programlisting>
</sect1>
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="cvs"><title>Version Control Guidelines</title>
- <para>To be filled. note on cvs comments. Don't only comment what you did,
- but also why you did it!
-</para>
- </sect1>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="testing"><title>Testing Guidelines</title>
<para>To be filled.
</orderedlist>
</para>
</sect2>
+ <!-- XXX: Document how to write test reports and where to send them -->
+ </sect1>
- <!-- ~~~~~ New section ~~~~~ -->
- <sect2 id="testing-report"><title>Test reports</title>
- <para>
-Please submit test reports only with the <ulink url="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005">test form</ulink>
-at sourceforge. Three simple steps:
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="newrelease"><title>Releasing a New Version</title>
+ <para>
+ When we release versions of <application>Privoxy</application>,
+ our work leaves our cozy secret lab and has to work in the cold
+ RealWorld[tm]. Once it is released, there is no way to call it
+ back, so it is very important that great care is taken to ensure
+ that everything runs fine, and not to introduce problems in the
+ very last minute.
+ </para>
+ <para>
+ So when releasing a new version, please adhere exactly to the
+ procedure outlined in this chapter.
+ </para>
+
+ <para>
+ The following programs are required to follow this process:
+ <filename>ncftpput</filename> (ncftp), <filename>scp, ssh</filename> (ssh),
+ <filename>gmake</filename> (GNU's version of make), autoconf, cvs.
+ </para>
+
+ <sect2 id="versionnumbers">
+ <title>Version numbers</title>
+
+ <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. 3.0.0), where:
<itemizedlist>
-
- <listitem><para>Select category: the distribution you test on.</para></listitem>
- <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
- <listitem><para>Fill the Summary and Detailed Description with something
- intelligent (keep it short and precise).</para>
+ <listitem>
+ <para>
+ X, the version major, is rarely ever changed. It is increased by one if
+ turning a development branch into stable substantially changes the functionality,
+ user interface or configuration syntax. Majors 1 and 2 were
+ <application>Junkbuster</application>, and 3 will be the first stable
+ <application>Privoxy</application> release.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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 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 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Z, the point or sub version, represents a release of the software within a branch.
+ It is therefore incremented immediately before each code freeze.
+ In development branches, only the even point versions correspond to actual releases,
+ while the odd ones denote the evolving state of the sources on CVS in between.
+ It follows that Z is odd on CVS in development branches most of the time. There, it gets
+ increased to an even number immediately before a code freeze, and is increased to an odd
+ number again immediately thereafter.
+ 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>
- Do not mail to the mailinglist (we cannot keep track on issues there).
- </para>
- </sect2>
-
- </sect1>
-
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="newrelease"><title>Releasing a new version</title>
+ </para>
<para>
- To minimize trouble with distribution contents, webpage
- errors and the like, we strongly encourage you
- to follow this section if you prepare a new release of
- code or new pages on the webserver.
+ 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>
- The following programs are required to follow this process:
- <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
-<filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
+ 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>
+
<sect2 id="beforerelease">
- <title>Before the Release</title>
+ <title>Before the Release: Freeze</title>
<para>
The following <emphasis>must be done by one of the
- developers</emphasis> prior to each new release:
+ developers</emphasis> prior to each new release.
</para>
<para>
<itemizedlist>
<para>
Make sure that everybody who has worked on the code in the last
couple of days has had a chance to yell <quote>no!</quote> in case
- they have pending changes/fixes in their pipelines.
+ they have pending changes/fixes in their pipelines. Announce the
+ freeze so that nobody will interfere with last minute changes.
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- Increment the version number in <filename>configure.in</filename> in
- CVS. Also, the RPM release number in
- <filename>configure.in</filename>. Do NOT touch version information
- after export from CVS. <emphasis>All packages</emphasis> will use the
- version and release data from <filename>configure.in</filename>.
- Local files should not be changed, except prior to a CVS commit!!!
- This way we are all on the same page!
+ Increment the version number (point from odd to even in development
+ branches!) in <filename>configure.in</filename>. (RPM spec files
+ will need to be incremented as well.)
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- If the default actionsfile has changed since last release,
- bump up its version info in this line:
+ If <filename>default.action</filename> has changed since last
+ release (i.e. software release or standalone actions file release),
+ bump up its version info to A.B in this line:
</para>
- <para>
+ <para>
<programlisting>
{+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
- </programlisting>
+</programlisting>
</para>
- <para>
+ <para>
Then change the version info in doc/webserver/actions/index.php,
line: '$required_actions_file_version = "A.B";'
</para>
- </listitem>
+ </listitem>
<listitem>
<para>
- Tag all files in CVS with the version number with
- <quote><command>cvs tag v_X_Y_Z</command></quote> (where X = major, Y
- = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
- etc.
+ 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)
+ 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>
<listitem>
<para>
- The first package uploaded should be the official
- <quote>tarball</quote> release. This is built with the
- <quote><command>make tarball-dist</command></quote> Makefile
- target, and then can be uploaded with
- <quote><command>make tarball-upload</command></quote> (see below).
+ 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>
+ </listitem>
+ <listitem>
+ <para>
+ Tag all files in CVS with the version number with
+ <quote><command>cvs tag v_X_Y_Z</command></quote>.
+ Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the release was in a development branch, increase the point version
+ from even to odd (X.Y.(Z+1)) again in <filename>configure.in</filename> and
+ commit your change.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ On the webserver, copy the user manual to a new top-level directory
+ called <filename>X.Y.Z</filename>. This ensures that help links from the CGI
+ pages, which have the version as a prefix, will go into the right version of the manual.
+ If this is a development branch release, also symlink <filename>X.Y.(Z-1)</filename>
+ to <filename>X.Y.Z</filename> and <filename>X.Y.(Z+1)</filename> to
+ <filename>.</filename> (i.e. dot).
</para>
- </listitem>
+ </listitem>
</itemizedlist>
- </para>
- </sect2>
-
- <sect2 id="newrelease-web"><title>Update the webserver</title>
- <para>
- All files must be group-readable and group-writable (or no one else
- will be able to change them). To update the webserver, create any
- pages locally in the <filename>doc/webserver</filename> directory (or
- create new directories under <filename>doc/webserver</filename>), then do
- </para>
- <para>
- <programlisting>
- make webserver
- </programlisting>
- </para>
- <para>
- Note that <quote><command>make dok</command></quote>
- (or <quote><command>make redhat-dok</command></quote>) creates
- <filename>doc/webserver/user-manual</filename>,
- <filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
- <filename>doc/webserver/man-page</filename> automatically.
- </para>
- <para>
- Please do NOT use any other means of transferring files to the
- webserver. <quote><command>make webserver</command></quote> not only
- uploads, but will make sure that the appropriate permissions are
- preserved for shared group access.
- </para>
+ </para>
</sect2>
- <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
- <para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- first.
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do
- </para>
- <para>
- <programlisting>
- make suse-dist or make redhat-dist
- </programlisting>
- </para>
- <para>
- To upload the package to Sourceforge, simply issue
- </para>
- <para>
- <programlisting>
- make suse-upload or make redhat-upload
- </programlisting>
- </para>
- <para>
- Go to the displayed URL and release the file publicly on Sourceforge.
- </para>
- </sect2>
+ <sect2 id="therelease">
+ <title>Building and Releasing the Packages</title>
+ <para>
+ Now the individual packages can be built and released. Note that for
+ GPL reasons the first package to be released is always the source tarball.
+ </para>
- <sect2 id="newrelease-os2"><title>OS/2</title>
- <para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- cd ..
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
- </programlisting>
- </para>
- <para>
- You will need a mix of development tools.
- The main compilation takes place with IBM Visual Age C++.
- Some ancillary work takes place with GNU tools, available from
- various sources like hobbes.nmsu.edu.
- Specificially, you will need <filename>autoheader</filename>,
- <filename>autoconf</filename> and <filename>sh</filename> tools.
- The packaging takes place with WarpIN, available from various sources, including
- its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
- </para>
- <para>
- Change directory to the <filename>os2setup</filename> directory.
- Edit the os2build.cmd file to set the final executable filename.
- For example,
- <programlisting>
- installExeName='privoxyos2_setup_X.Y.Z.exe'
- </programlisting>
- Next, edit the <filename>IJB.wis</filename> file so the release number matches
- in the <filename>PACKAGEID</filename> section:
- <programlisting>
- PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
- </programlisting>
- You're now ready to build. Run:
- <programlisting>
- os2build
- </programlisting>
- And in the <filename>./files</filename> directory you will have the
- WarpIN-installable executable.
- Upload this anonymously to
- <filename>uploads.sourceforge.net/incoming</filename>, create a release
- for it, and you're done.
- </para>
- </sect2>
+ <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> (just press return when
+ asked for a password):
+ </para>
- <sect2 id="newrelease-solaris"><title>Solaris</title>
- <para>
- Login to Sourceforge's compilefarm via ssh
- </para>
- <para>
- <programlisting>
- ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system (not the Debian one). If you have
- downloaded <application>Privoxy</application> before,
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Run:
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then run
- </para>
- <para>
- <programlisting>
- gmake solaris-dist
- </programlisting>
- </para>
- <para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
- solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
- </para>
- </sect2>
+ <para>
+ <programlisting>
+ mkdir dist # delete or choose different name if it already exists
+ cd dist
+ 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>
- <sect2 id="newrelease-windows"><title>Windows</title>
- <para>
- Ensure that you have the latest code version. Hence run
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- Run:
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
- </sect2>
+ <para>
+ <emphasis>Do NOT change</emphasis> a single bit, including, but not limited to
+ version information after export from CVS. This is to make sure that
+ all release packages, and with them, all future bug reports, are based
+ on exactly the same code.
+ </para>
- <sect2 id="newrelease-debian"><title>Debian</title>
- <para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- first. Run:
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
- </sect2>
+ <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>
- <sect2 id="newrelease-macosx"><title>Mac OSX</title>
+ <para>
+ Please find additional instructions for the source tarball and the
+ individual platform dependent binary packages below. And details
+ 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> 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 (<filename>default.action</filename> and
+ <filename>default.filter</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>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- cd ..
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
- </programlisting>
- </para>
- <para>
- From the osxsetup directory, run:
- <programlisting>
- build
- </programlisting>
- </para>
- <para>
- This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
- <filename>configure</filename> as well as <filename>make</filename>.
- Finally, it will copy over the necessary files to the ./osxsetup/files directory
- for further processing by <filename>PackageMaker</filename>.
- </para>
- <para>
- Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
- name to match the release, and hit the "Create package" button.
- If you specify ./Privoxy.pkg as the output package name, you can then create
- the distributable zip file with the command:
- <programlisting>
-zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
- </programlisting>
- You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
- <filename>uploads.sourceforge.net/incoming</filename>,
- create a release for it, and you're done.
- </para>
- </sect2>
+ 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>
+ <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>
+
+ </sect3>
- <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
+ <sect3 id="newrelease-tarball"><title>Source Tarball</title>
<para>
- Change the version number of <application>Privoxy</application> in the
- configure.in file. Run:
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- Then ...
+ 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>
- Login to Sourceforge's compilefarm via ssh:
- </para>
- <para>
- <programlisting>
- ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system. If you have downloaded Privoxy
- before,
- </para>
- <para>
- <programlisting>
+ <programlisting>
cd current
- 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
- </programlisting>
- </para>
- <para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Run:
- </para>
- <para>
- <programlisting>
autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then run:
- </para>
- <para>
- <programlisting>
- gmake freebsd-dist
- </programlisting>
- </para>
- <para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
- freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
- </para>
- </sect2>
-
- <sect2 id="newrelease-tarball"><title>Tarball</title>
+</programlisting>
+ </para>
<para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- first. Run:
- </para>
- <para>
- <programlisting>
- make clobber
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do:
- </para>
- <para>
- <programlisting>
+ Then do:
+ </para>
+ <para>
+ <programlisting>
make tarball-dist
- </programlisting>
- </para>
- To upload the package to Sourceforge, simply issue
- </para>
- <programlisting>
+</programlisting>
+ </para>
+ <para>
+ To upload the package to Sourceforge, simply issue
+ </para>
+ <para>
make tarball-upload
- </programlisting>
- </para>
- <para>
- Goto the displayed URL and release the file publicly on Sourceforge.
+</programlisting>
</para>
- </sect2>
+ <para>
+ Go to the displayed URL and release the file publicly on Sourceforge.
+ For the change log field, use the relevant section of the
+ <filename>ChangeLog</filename> file.
+ </para>
+ </sect3>
- <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
+ <sect3 id="newrelease-rpm"><title>SuSE, Conectiva or Red Hat RPM</title>
<para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
+ In following text, replace <replaceable class="parameter">dist</replaceable>
+ with either <quote>rh</quote> for Red Hat or <quote>suse</quote> for SuSE.
+ </para>
+ <para>
+ First, <emphasis>make sure that you have freshly exported the right
+ version into an empty directory</emphasis>. (See "Building and releasing
+ packages" above).
+ </para>
+ <para>
+ As the only exception to not changing anything after export from CVS,
+ now examine the file <filename>privoxy-</filename><replaceable class="parameter">dist</replaceable><filename>.spec</filename>
+ and make sure that the version information and the RPM release number are
+ correct. The RPM release numbers for each version start at one. Hence it must
+ be reset to one if this is the first RPM for
+ <replaceable class="parameter">dist</replaceable> which is built from version
+ X.Y.Z. Check the
+ <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">file
+ list</ulink> if unsure. Else, it must be set to the highest already available RPM
+ release number for that version plus one.
+ </para>
+ <para>
+ Then run:
+ </para>
+ <para>
+ <programlisting>
cd current
- 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
- </programlisting>
- </para>
- <para>
- first. Run:
- </para>
- <para>
- <programlisting>
autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
- </sect2>
+</programlisting>
+ </para>
+ <para>
+ Then do
+ </para>
+ <para>
+ <programlisting>
+ make <replaceable class="parameter">dist</replaceable>-dist
+</programlisting>
+ </para>
+ <para>
+ To upload the package to Sourceforge, simply issue
+ </para>
+ <para>
+ <programlisting>
+ make <replaceable class="parameter">dist</replaceable>-upload <replaceable class="parameter">rpm_packagerev</replaceable>
+</programlisting>
+ </para>
+ <para>
+ where <replaceable class="parameter">rpm_packagerev</replaceable> is the
+ RPM release number as determined above.
+ Go to the displayed URL and release the file publicly on Sourceforge.
+ Use the release notes and change log from the source tarball package.
+ </para>
+ </sect3>
- <sect2 id="newrelease-amiga"><title>Amiga OS</title>
+ <sect3 id="newrelease-os2"><title>OS/2</title>
<para>
- Ensure that you have the latest code version. Hence run:
- </para>
- <para>
- <programlisting>
- cd current
- 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
- </programlisting>
- </para>
- <para>
- first. Run:
- </para>
- <para>
- <programlisting>
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
- </sect2>
+ 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 OS/2 Setup module:
+ </para>
+ <para>
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
+</programlisting>
+ </para>
+ <para>
+ You will need a mix of development tools.
+ The main compilation takes place with IBM Visual Age C++.
+ Some ancillary work takes place with GNU tools, available from
+ various sources like hobbes.nmsu.edu.
+ Specificially, you will need <filename>autoheader</filename>,
+ <filename>autoconf</filename> and <filename>sh</filename> tools.
+ The packaging takes place with WarpIN, available from various sources, including
+ its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
+ </para>
+ <para>
+ Change directory to the <filename>os2setup</filename> directory.
+ Edit the os2build.cmd file to set the final executable filename.
+ For example,
+ </para>
+ <para>
+ <programlisting>
+ installExeName='privoxyos2_setup_X.Y.Z.exe'
+</programlisting>
+ </para>
+ <para>
+ Next, edit the <filename>IJB.wis</filename> file so the release number matches
+ in the <filename>PACKAGEID</filename> section:
+ </para>
+ <para>
+ <programlisting>
+ PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
+</programlisting>
+ </para>
+ <para>
+ You're now ready to build. Run:
+ </para>
+ <para>
+ <programlisting>
+ os2build
+</programlisting>
+ </para>
+ <para>
+ You will find the WarpIN-installable executable in the
+ <filename>./files</filename> directory. Upload this anonymously to
+ <filename>uploads.sourceforge.net/incoming</filename>, create a release
+ for it, and you're done. Use the release notes and Change Log from the
+ source tarball package.
+ </para>
+ </sect3>
- <sect2 id="newrelease-aix"><title>AIX</title>
+ <sect3 id="newrelease-solaris"><title>Solaris</title>
<para>
- Login to Sourceforge's compilefarm via ssh:
- </para>
- <programlisting>
+ Login to Sourceforge's compilefarm via ssh:
+ </para>
+ <para>
ssh cf.sourceforge.net
- </programlisting>
- </para>
- <para>
- Choose the right operating system. If you have downloaded Privoxy
- before:
- </para>
- <para>
- <programlisting>
+</programlisting>
+ </para>
+ <para>
+ Choose the right operating system (not the Debian one).
+ When logged in, <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
- 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
- </programlisting>
- </para>
- <para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Run:
- </para>
- <para>
- <programlisting>
autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then run:
- </para>
- <para>
- <programlisting>
- make aix-dist
- </programlisting>
- </para>
- <para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
- aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
- </para>
- </sect2>
+</programlisting>
+ </para>
+ <para>
+ Then run
+ </para>
+ <para>
+ <programlisting>
+ gmake solaris-dist
+</programlisting>
+ </para>
+ <para>
+ which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
+ solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
+ to manually upload the archive to Sourceforge's ftp server and release
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
+ </para>
+ </sect3>
- </sect1>
-
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
-<!-- Include contacting.sgml -->
- &contacting;
-<!-- end contacting -->
- </sect1>
-
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="copyright"><title>Copyright and History</title>
+ <sect3 id="newrelease-windows"><title>Windows</title>
+ <para>
+ Use the <ulink url="http://www.fruitbat.org/Cygwin/index.html#cygwincirca">
+ Cygwin Time Machine</ulink> to install the last 1.5 version of Cygwin.
+ Run the following commands from within the Cygwin 1.5 bash shell.
+ </para>
+ <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 Windows setup module:
+ </para>
+ <para>
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
+</programlisting>
+ </para>
+ <para>
+ Then you can build the package. This is fully automated, and is
+ controlled by <filename>winsetup/GNUmakefile</filename>.
+ All you need to do is:
+ </para>
+ <para>
+ <programlisting>
+ cd winsetup
+ make
+</programlisting>
+ </para>
+ <para>
+ Now you can manually rename <filename>privoxy_setup.exe</filename> to
+ <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
+ SourceForge. When releasing the package on SourceForge, use the release notes
+ and Change Log from the source tarball package.
+ </para>
+ </sect3>
-<sect2><title>Copyright</title>
-<!-- Include copyright.sgml -->
- ©right;
-<!-- end -->
-</sect2>
+ <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 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, 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>
-<sect2><title>History</title>
-<!-- Include history.sgml -->
- &history;
-<!-- end -->
-</sect2>
+ <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).
+ </para>
+ <para>
+ There are three modules available in the CVS repository for use on Mac
+ OS X, though technically only two of them generate a release (the other
+ can be used to install from source).
+ </para>
+ <sect4 id="OS-X-OSXPackageBuilder-module">
+ <title>OSXPackageBuilder module</title>
+ <para>
+ The OSXPackageBuilder module generates OS X installer packages
+ supporting all Macs running OS X 10.4 and above. Obtain it from CVS as
+ follows into a folder parallel to the exported privoxy source:
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
+</programlisting>
+ </para>
+ <para>
+ The module contains complete instructions on its usage in the file
+ <filename>OS X Package Builder HOWTO.txt</filename>.
+ </para>
+ <para>
+ Once the package(s) have been generated, you can then upload them
+ directly to the Files section of the Sourceforge project in the
+ Macintosh (OS X) folder. Each new version release of Privoxy should
+ have a new subfolder created in which to store its files. Please
+ ensure that the folder contains a readme file that makes it clear
+ which package is for whichversion of OS X.
+ </para>
+ </sect4>
+ <sect4 id="OS-X-osxsetup-module">
+ <title>osxsetup module (DEPRECATED)</title>
+ <para>
+ <emphasis>This module is deprecated since the installer it generates
+ places all Privoxy files in one folder in a non-standard location, and
+ supports only Intel Macs running OS X 10.6 or higher.</emphasis>
+ </para>
+ <para>
+ Check out the module from CVS as follows into a folder parallel to the
+ exported privoxy source:
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
+</programlisting>
+ </para>
+ <para>
+ Then run:
+ </para>
+ <para>
+ <programlisting>
+ cd osxsetup
+ build
+</programlisting>
+ </para>
+ <para>
+ This will run <filename>autoheader</filename>, <filename>autoconf</filename>
+ and <filename>configure</filename> as well as <filename>make</filename>.
+ Finally, it will copy over the necessary files to the ./osxsetup/files
+ directory for further processing by <filename>PackageMaker</filename>.
+ </para>
+ <para>
+ Bring up PackageMaker with the PrivoxyPackage.pmsp definition file,
+ modify the package name to match the release, and hit the "Create
+ package" button. If you specify ./Privoxy.pkg as the output package
+ name, you can then create the distributable zip file with the command:
+ </para>
+ <para>
+ <programlisting>
+ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
+</programlisting>
+ </para>
+ <para>
+ You can then upload this file directly to the Files section of the
+ Sourceforge project in the Macintosh (OS X) folder. Each new version
+ release of Privoxy should have a new subfolder created in which to
+ store its files.
+ Please ensure that the folder contains a readme file that makes it
+ clear which version(s) of OS X the package supports.
+ </para>
+ </sect4>
+ <sect4 id="OS-X-macsetup-module">
+ <title>macsetup module</title>
+ <para>
+ The macsetup module is ideal if you wish to build and install Privoxy
+ from source on a single machine.
+ </para>
+ <para>
+ Check out the module from CVS as follows into a folder parallel to the
+ exported privoxy source:
+ <programlisting>
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup
+</programlisting>
+ </para>
+ <para>
+ The module contains complete instructions on its usage in its
+ <filename>README</filename> file. The end result will be the
+ exported version of Privoxy installed on the build machine.
+ </para>
+ </sect4>
+ </sect3>
+
+ <sect3 id="newrelease-freebsd"><title>FreeBSD</title>
+ <para>
+ Update the www/privoxy port and submit a diff upstream.
+ For details see the <ulink url="https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/">FreeBSD Porter's Handbook</ulink>.
+ </para>
+ </sect3>
+
+ <sect2 id="releasing">
+ <title>Uploading and Releasing Your Package</title>
+ <para>
+ After the package is ready, it is time to upload it
+ to SourceForge, and go through the release steps. The upload
+ is done via FTP:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Upload to: <ulink url="ftp://upload.sourceforge.net/incoming">ftp://upload.sourceforge.net/incoming</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ user: <literal>anonymous</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ password: <literal>ijbswa-developers@lists.sourceforge.net</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Or use the <command>make</command> targets as described above.
+ </para>
+ <para>
+ 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
+ of <literal>$VERSION ($CODE_STATUS)</literal>, e.g. <emphasis>&p-version;
+ (beta)</emphasis>.
+ </para>
+ <para>
+ Now just follow the prompts. Be sure to add any appropriate Release
+ notes. You should see your freshly uploaded packages in
+ <quote>Step 2. Add Files To This Release</quote>. Check the
+ appropriate box(es). Remember at each step to hit the
+ <quote>Refresh/Submit</quote> buttons! You should now see your
+ file(s) listed in Step 3. Fill out the forms with the appropriate
+ information for your platform, being sure to hit <quote>Update</quote>
+ for each file. If anyone is monitoring your platform, check the
+ <quote>email</quote> box at the very bottom to notify them of
+ the new package. This should do it!
+ </para>
+ <para>
+ If you have made errors, or need to make changes, you can go through
+ essentially the same steps, but select <literal>Edit Release</literal>,
+ instead of <literal>Add Release</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="afterrelease">
+ <title>After the Release</title>
+ <para>
+ When all (or: most of the) packages have been uploaded and made available,
+ send an email to the <ulink url="mailto:privoxy-announce@lists.privoxy.org">announce
+ mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
+ include the
+ <ulink url="https://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). Other news sites
+ and release oriented sites, such as Freshmeat, should also be notified.
+ </para>
+ </sect2>
</sect1>
-
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="seealso"><title>See also</title>
-<!-- Include seealso.sgml -->
- &seealso;
-<!-- end -->
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="webserver-update"><title>Update the Webserver</title>
+ <para>
+ 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 stable-branch documentation source
+ SGML files, do:
+ </para>
+ <para>
+ <programlisting>
+ make dok
+</programlisting>
+ </para>
+ <para>
+ That will generate <filename>doc/webserver/user-manual</filename>,
+ <filename>doc/webserver/developer-manual</filename>,
+ <filename>doc/webserver/faq</filename>,
+ <filename>doc/webserver/index.html</filename> automatically.
+ </para>
+ <para>
+ 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
+ [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
+ the <filename>doc/webserver/*</filename> directory (or
+ create new directories under <filename>doc/webserver</filename>).
+ </para>
+ <para>
+ 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>
+ make webserver
+</programlisting>
+ </para>
+ <para>
+ This will do the upload to <ulink url="https://www.privoxy.org/">the
+ webserver</ulink> (www.privoxy.org) and ensure all files and directories
+ there are group writable.
+ </para>
+ <para>
+ Please do <emphasis>NOT</emphasis> use any other means of transferring
+ 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>
<!--
- This program is free software; you can redistribute it
+ This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General
Public License as published by the Free Software
Foundation; either version 2 of the License, or (at
or write to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- $Log: developer-manual.sgml,v $
- Revision 1.28 2002/04/08 22:59:26 hal9
- Version update. Spell chkconfig correctly :)
-
- Revision 1.27 2002/04/08 15:31:18 hal9
- Touch ups to documentation section.
-
- Revision 1.26 2002/04/07 23:50:08 hal9
- Documentation changes to reflect HTML docs now in CVS, and new generated files
- list.
-
- Revision 1.25 2002/04/06 05:07:28 hal9
- -Add privoxy-man-page.sgml, for man page.
- -Add authors.sgml for AUTHORS (and p-authors.sgml)
- -Reworked various aspects of various docs.
- -Added additional comments to sub-docs.
-
- Revision 1.24 2002/04/04 21:33:37 hal9
- More on documenting the documents.
-
- Revision 1.23 2002/04/04 18:46:47 swa
- consistent look. reuse of copyright, history et. al.
-
- Revision 1.22 2002/04/04 17:27:56 swa
- more single file to be included at multiple points. make maintaining easier
-
- Revision 1.21 2002/04/04 06:48:37 hal9
- Structural changes to allow for conditional inclusion/exclusion of content
- based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
- definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
- eventually be set by Makefile.
- More boilerplate text for use across multiple docs.
-
- Revision 1.20 2002/04/04 03:28:27 david__schmidt
- Add Mac OSX section
-
- Revision 1.19 2002/04/03 15:09:42 david__schmidt
- Add OS/2 build section
-
- Revision 1.18 2002/04/03 03:51:48 hal9
- Touch ups.
-
- Revision 1.17 2002/04/03 01:21:17 hal9
- Implementing Andreas's suggestions for Release sections.
-
- Revision 1.16 2002/03/31 23:04:40 hal9
- Fleshed out the doc section, and added something for an intro so it was not
- blank.
-
- Revision 1.15 2002/03/30 22:29:47 swa
- wrong make flavour
-
- Revision 1.14 2002/03/30 19:04:08 swa
- people release differently. no good.
- I want to make parts of the docs only.
-
- Revision 1.13 2002/03/27 01:16:41 hal9
- ditto
-
- Revision 1.12 2002/03/27 01:02:51 hal9
- Touch up on name change...
-
- Revision 1.11 2002/03/26 22:29:55 swa
- we have a new homepage!
-
- Revision 1.10 2002/03/24 12:33:01 swa
- more additions.
-
- Revision 1.9 2002/03/24 11:01:05 swa
- name change
-
- Revision 1.8 2002/03/23 15:13:11 swa
- renamed every reference to the old name with foobar.
- fixed "application foobar application" tag, fixed
- "the foobar" with "foobar". left junkbustser in cvs
- comments and remarks to history untouched.
-
- Revision 1.7 2002/03/11 13:13:27 swa
- correct feedback channels
-
- Revision 1.6 2002/02/24 14:25:06 jongfoster
- Formatting changes. Now changing the doctype to DocBook XML 4.1
- will work - no other changes are needed.
-
- Revision 1.5 2001/10/31 18:16:51 swa
- documentation added: howto generate docs in text and html
- format, howto move stuff to the webserver.
-
- Revision 1.4 2001/09/23 10:13:48 swa
- upload process established. run make webserver and
- the documentation is moved to the webserver. documents
- are now linked correctly.
-
- Revision 1.3 2001/09/13 15:27:40 swa
- cosmetics
-
- Revision 1.2 2001/09/13 15:20:17 swa
- merged standards into developer manual
-
- Revision 1.1 2001/09/12 15:36:41 swa
- source files for junkbuster documentation
-
- Revision 1.3 2001/09/10 17:43:59 swa
- first proposal of a structure.
-
- Revision 1.2 2001/06/13 14:28:31 swa
- docs should have an author.
-
- Revision 1.1 2001/06/13 14:20:37 swa
- first import of project's documentation for the webserver.
-
-->
</article>
projects / privoxy.git / blobdiff