<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
-<!entity p-version "2.9.15">
-<!entity p-status "beta">
-<!entity % p-not-stable "INCLUDE">
+<!entity p-version SYSTEM "doc_version.tmp">
+<!entity p-status SYSTEM "doc_status.tmp">
+<!entity % p-not-stable "IGNORE">
<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.5 2002/09/26 21:50:39 hal9 Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
========================================================================
NOTE: Please read developer-manual/documentation.html before touching
- anything in this, or other Privoxy documentation. You have been warned!
- Failure to abide by this rule will result in the revocation of your license
- to live a peaceful existence!
+ anything in this, or other Privoxy documentation.
========================================================================
-->
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 2.5 2002/09/26 21:50:39 hal9 Exp $</pubdate>
<!--
</para>
]]>
<para>
- The developer manual gives the users information on how to help the developer
- team. It provides guidance on coding, testing, documentation and other
- issues.
- </para>
+ The developer manual provides guidance on coding, testing, packaging, documentation
+ and other issues of importance to those involved with
+ <application>Privoxy</application> development. It is mandatory (and helpful!) reading
+ for anyone who wants to join the team.
+</para>
<!-- Include privoxy.sgml boilerplate text: -->
<!-- end boilerplate -->
<para>
+ <![%p-stable;[
+ Please note that this document is constantly evolving. This copy represents
+ the state at the release of version &p-version;. ]]>
You can find the latest version of the this manual at <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
Please see <link linkend="contact">the Contact section</link>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="quickstart"><title>Quickstart to Privoxy Development</title>
+ <!--
<para>
You'll need an account on <ulink
url="http://sourceforge.net/">Sourceforge</ulink> to support our
url="mailto:developers@privoxy.org">the list</ulink> and wait until a
project manager has added you.
</para>
+ -->
+ <para>
+ The first step is to join the <ulink
+ url="mailto:developers@privoxy.org">developer's mailing list</ulink>.
+ You can submit your ideas, or even better patches. Patches are best
+ submitted to the Sourceforge tracker set up for this purpose, but
+ can be sent to the list for review too.
+ </para>
<para>
- For the time being (read, this section is under construction), please
- refer to the extensive comments in the source code.
+ 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="cvs"><title>The CVS Repository</title>
<para>
- If you intend to help us with programming, documentation or packaging
- you will need write access to our holy grail, the CVS repository.
- Please read this chapter completely before accessing via CVS.
+ If you become part of the active development team, you will eventually
+ need write access to our holy grail, the CVS repository. One of the
+ team members will need to set this up for you. Please read
+ this chapter completely before accessing via CVS.
</para>
<sect2 id="cvsaccess"><title>Access to CVS</title>
</para>
</sect2>
- <sect2 id="cvscommit"><title>CVS Commit Guideline</title>
+ <sect2 id="cvsbranches">
+ <title>Branches</title>
+ <para>
+ Within the CVS repository, there are modules and branches. As
+ mentioned, the sources are in the <literal>current</literal>
+ <quote>module</quote>. Other modules are present for platform specific
+ issues. There is a webview of the CVS hierarchy at <ulink
+ url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/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).
+ And for testing bugfixes for the stable series. Just prior to each
+ stable series (e.g. 3.0.x), a branch is created just for stable series
+ releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable
+ release of any stable branch has taken place, this branch is
+ <emphasis>only used for bugfixes</emphasis>, which have had prior
+ testing before being committed to CVS. (See <link
+ linkend="versionnumbers">Version Numbers</link> below for details on
+ versioning.)
+ </para>
+ <para>
+ This will result in at least two active branches, which means there may
+ be occasions that require the same (or similar) item to be
+ checked into to two different places (assuming its a bugfix and needs
+ fixing in both the stable and unstable trees). This also means that in
+ order to have access to both trees, both will have to be checked out
+ separately. Use the <literal>cvs -r</literal> flag to check out a
+ branch, e.g: <literal>cvs co -r v_3_0_branch current</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
<para>
The source tree is the heart of every software project. Every effort must
be made to ensure that it is readable, compilable and consistent at all
- times. We therefore ask anyone with CVS access to strictly adhere to the
- following guidelines:
+ times. There are differing guidelines for the stable branch and the
+ main development trunk, and we ask anyone with CVS access to strictly
+ adhere to the following guidelines:
+ </para>
+
+ <para>
+ Basic Guidelines, for all branches:
+ </para>
+ <para>
<itemizedlist>
<listitem><para>
Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
</para></listitem>
<listitem><para>
If your changes span multiple files, and the code won't recompile unless
- all changes are commited (e.g. when changing the signature of a function),
- then commit all files one after another, without long delays in beween.
+ all changes are committed (e.g. when changing the signature of a function),
+ then commit all files one after another, without long delays in between.
If necessary, prepare the commit messages in advance.
</para></listitem>
<listitem><para>
Before changing things on CVS, make sure that your changes are in line
- with the team's general consensus on what should be done (see below).
+ with the team's general consensus on what should be done.
</para></listitem>
+ <listitem>
+ <para>
+ Note that near a major public release, we get more cautious.
+ There is always the possibility to submit a patch to the <ulink
+ url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch
+ tracker</ulink> instead.
+ </para>
+ </listitem>
</itemizedlist>
</para>
+
+ <para>
+ Stable branches are handled with decidedly more care, especially after
+ the initial *.*.0 release, and we are just in bugfix mode. In addition
+ to the above, the below applies only to the stable branch (currently
+ the <literal>v_3_0_branch</literal> branch):
+ </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="http://sourceforge.net/tracker/?group_id=11118&atid=311118">http://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
+ Then ask for peer review.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Do not even think about anything except bugfixes. No new features!
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
</sect2>
+<!--
+ This sounds vague, dated, and out of step with current development style.
+ Removing 09/03/02, HB.
+
<sect2 id="cvswhenask"><title>Discussing Changes First</title>
<para>
- We don't have a too formal policy on this, just use common sense. Hints: If it is..
- <orderedlist numeration="arabic">
+ We don't have a formal policy for the development branch, just use
+ common sense. Hints: If it is..
+ <orderedlist numeration="arabic">
<listitem><para>
- ..a bugfix / clean-up / cosmetic thing: shoot
+ ..a bug-fix / clean-up / cosmetic thing: shoot
</para></listitem>
<listitem><para>
..a new feature that can be turned off: shoot
tracker</ulink> instead.
</para>
</sect2>
+ -->
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
course this, the <citetitle>developer-manual</citetitle> in this format.
The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
- <citetitle>privoxy.1</citetitle> (man page) files are also now maintained
- as Docbook SGML. The finished files are all in the top-level source
- directory are generated files! Also, <filename>index.html</filename>, the
- <application>Privoxy</application> home page, is maintained as SGML.
+ <citetitle>privoxy.1</citetitle> (man page), and
+ <citetitle>config</citetitle> files are also now maintained as Docbook
+ SGML. These files, when built, in the top-level source directory are
+ generated files! Also, the <application>Privoxy</application> <filename>index.html</filename> (and a
+ variation on this file, <filename>privoxy-index.html</filename>,
+ meant for inclusion with doc packages), are maintained as SGML as well.
<emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
- contact someone involved in the documentation (at present Stefan and
- Hal).
+ contact someone involved in the documentation (at present Hal).
</para>
+ <para>
+ <filename>config</filename> requires some special handling. The reason it
+ is maintained this way is so that the extensive comments in the file
+ mirror those in <citetitle>user-manual</citetitle>. But the conversion
+ process requires going from SGML to HTML to text to special formatting
+ required for the embedded comments. Some of this does not survive so
+ well. Especially some of the examples that are longer than 80 characters.
+ The build process for this file outputs to <filename>config.new</filename>,
+ which should be reviewed for errors and mis-formatting. Once satisfied
+ that it is correct, then it should be hand copied to
+ <filename>config</filename>.
+ </para>
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<filename>INSTALL</filename>) are maintained as plain text files in the
<listitem><para>
First, build the docs by running <computeroutput>make
dok</computeroutput> (or alternately <computeroutput>make
- redhat-dok</computeroutput>).
+ redhat-dok</computeroutput>). For PDF docs, do <computeroutput>make
+ dok-pdf</computeroutput>.
</para></listitem>
<listitem><para>
Run <computeroutput>make webserver</computeroutput> which copies all
<listitem>
<para>
Our documents are available in differing formats. Right now, they
- are just plain text, and HTML, but PDF, and others is always a
+ are just plain text, TML, and PDF, but others are always a
future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</para>
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accommodate this.</para>
+ free/unload/destructor type function to accommodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.5 2002/09/26 21:50:39 hal9 Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.5 2002/09/26 21:50:39 hal9 Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
intelligent (keep it short and precise).</para>
</listitem>
</itemizedlist>
- Do not mail to the mailinglist (we cannot keep track on issues there).
+ Do not mail to the mailing list (we cannot keep track on issues there).
</para>
</sect2>
<para>
First you need to determine which version number the release will have.
<application>Privoxy</application> version numbers consist of three numbers,
- separated by dots, like in X.Y.Z, where:
+ separated by dots, like in X.Y.Z (e.g. <literal>3.0.0</literal>), where:
<itemizedlist>
<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 bugfixes are made, and 2N+1, the development branch, in
+ being added and only bug-fixes are made, and 2N+1, the development branch, in
which the further development of <application>Privoxy</application> takes
place.
This enables us to turn the code upside down and inside out, while at the same time
providing and maintaining a stable version.
- The minor is reset to zero (and one) when the major is inrcemented. When a development
+ The minor is reset to zero (and one) when the major is incremented. When a development
branch has matured to the point where it can be turned into stable, the old stable branch
2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
new stable branch 2N+2, and a new development branch 2N+3 is opened.
This ensures that builds from CVS snapshots are easily distinguished from released versions.
The point version is reset to zero when the minor changes.
</para>
+ <para>
+ Stable branches work a little differently, since there should be
+ little to no development happening in such branches. Remember,
+ only bugfixes, which presumably should have had some testing
+ before being committed. Stable branches will then have their
+ version reported as <literal>0.0.0</literal>, during that period
+ between releases when changes are being added. This is to denote
+ that this code is <emphasis>not for release</emphasis>. Then
+ as the release nears, the version is bumped according: e.g.
+ <literal>3.0.1 -> 0.0.0 -> 3.0.2</literal>.
+ </para>
</listitem>
</itemizedlist>
</para>
+ <para>
+ In summary, the main CVS trunk is the development branch where new
+ features are being worked on for the next stable series. This should
+ almost always be where the most activity takes place. There is always at
+ least one stable branch from the trunk, e.g now it is
+ <literal>3.0</literal>, which is only used to release stable versions.
+ Once the initial *.0 release of the stable branch has been done, then as a
+ rule, only bugfixes that have had prior testing should be committed to
+ the stable branch. Once there are enough bugfixes to justify a new
+ release, the version of this branch is again incremented Example: 3.0.0
+ -> 3.0.1 -> 3.0.2, etc are all stable releases from within the stable
+ branch. 3.1.x is currently the main trunk, and where work on 3.2.x is
+ taking place. If any questions, please post to the devel list
+ <emphasis>before</emphasis> committing to a stable branch!
+ </para>
+ <para>
+ Developers should remember too that if they commit a bugfix to the stable
+ branch, this will more than likely require a separate submission to the
+ main trunk, since these are separate development trees within CVS. If you
+ are working on both, then this would require at least two separate check
+ outs (i.e main trunk, <emphasis>and</emphasis> the stable release branch,
+ which is <literal>v_3_0_branch</literal> at the moment).
+ </para>
</sect2>
<listitem>
<para>
Increment the version number (point from odd to even in development
- branches!) in <filename>configure.in</filename>.
+ branches!) in <filename>configure.in</filename>. (RPM spec files
+ will need to be incremented as well.)
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- If the HTML documentation is not in sync with the SGML sources
- you need to regenerate and upload it to the webserver. (If in
- doubt, just do it.) See the Section "Updating the webserver" in
- this manual for details.
+ All documentation should be rebuild after the version bump.
+ Finished docs should be then be committed to CVS (for those
+ without the ability to build these). Some docs may require
+ rather obscure processing tools. <filename>config</filename>,
+ the man page (and the html version of the man page), and the PDF docs
+ fall in this category. REAMDE, the man page, AUTHORS, and config
+ should all also be committed to CVS for other packagers. The
+ formal docs should be uploaded to the webserver. See the
+ Section "Updating the webserver" in this manual for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <citetitle>User Manual</citetitle> is also used for context
+ sensitive help for the CGI editor. This is version sensitive, so that
+ the user will get appropriate help for his/her release. So with
+ each release a fresh version should be uploaded to the webserver
+ (this is in addition to the main <citetitle>User Manual</citetitle>
+ link from the main page since we need to keep manuals for various
+ versions available). The CGI pages will link to something like
+ <literal>http://privoxy.org/$(VERSION)/user-manual/</literal>. This
+ will need to be updated for each new release. There is no Makefile
+ target for this at this time!!! It needs to be done manually.
</para>
</listitem>
+ <listitem>
+ <para>
+ All developers should look at the <filename>ChangeLog</filename> and
+ make sure noteworthy changes are referenced.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>Commit all files that were changed in the above steps!</emphasis>
<para>
For <emphasis>all</emphasis> types of packages, including the source tarball,
<emphasis>you must make sure that you build from clean sources by exporting
- the right version from CVS into an empty directory:</emphasis>.
+ the right version from CVS into an empty directory</emphasis> (just press return when
+ asked for a password):
</para>
<para>
on the Sourceforge release process below that.
</para>
+ <sect3 id="pack-guidelines">
+ <title>Note on Privoxy Packaging</title>
+ <para>
+ Please keep these general guidelines in mind when putting together
+ your package. These apply to <emphasis>all</emphasis> platforms!
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <application>Privoxy</application> <emphasis>requires</emphasis>
+ write access to: all <filename>*.action</filename> files, all
+ logfiles, and the <filename>trust</filename> file. You will
+ need to determine the best way to do this for your platform.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Please include up to date documentation. At a bare minimum:
+ </para>
+ <simplelist>
+ <member>
+ <filename>LICENSE</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>README</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>AUTHORS</filename> (top-level directory)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>man page</filename> (top-level directory, Unix-like
+ platforms only)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>The User Manual</filename> (doc/webserver/user-manual/)
+ </member>
+ </simplelist>
+ <simplelist>
+ <member>
+ <filename>FAQ</filename> (doc/webserver/faq/)
+ </member>
+ </simplelist>
+ <para>
+ Also suggested: <filename>Developer Manual</filename>
+ (doc/webserver/developer-manual) and <filename>ChangeLog</filename>
+ (top-level directory). <filename>FAQ</filename> and the manuals are
+ HTML docs. There are also text versions in
+ <filename>doc/text/</filename> which could conceivably also be
+ included.
+ </para>
+ <para>
+ The documentation has been designed such that the manuals are linked
+ to each other from parallel directories, and should be packaged
+ that way. <filename>privoxy-index.html</filename> can also be
+ included and can serve as a focal point for docs and other links of
+ interest (and possibly renamed to <filename>index.html</filename>).
+ This should be one level up from the manuals. There is a link also
+ on this page to an HTMLized version of the man page. To avoid 404 for
+ this, it is in CVS as
+ <filename>doc/webserver/man-page/privoxy-man-page.html</filename>,
+ and should be included along with the manuals. There is also a
+ css stylesheets that can be included for better presentation:
+ <filename>p_doc.css</filename>. This should be in the same directory
+ with <filename>privoxy-index.html</filename>, (i.e. one level up from
+ the manual directories).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>user.action</filename> is designed for local preferences.
+ Make sure this does not get overwritten!
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Other configuration files should be installed as the new defaults,
+ but all previously installed configuration files should be preserved
+ as backups. This is just good manners :-)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Please check platform specific notes in this doc, if you haven't
+ done <quote>Privoxy</quote> packaging before for other platform
+ specific issues. Conversely, please add any notes that you know
+ are important for your platform (or contact one of the doc
+ maintainers to do this if you can't).
+ </para>
+ </listitem>
+ <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>
+
<sect3 id="newrelease-tarball"><title>Source Tarball</title>
<para>
First, <emphasis>make sure that you have freshly exported the right
</para>
<para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd winsetup
- make
+ cd winsetup
+ make
</programlisting>
</para>
<para>
<sect3 id="newrelease-debian"><title>Debian</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then, run:
- </para>
- <para>
- <programlisting>
- cd current
- autoheader && autoconf && ./configure
+ First, <emphasis>make sure that you have freshly exported the
+ right version into an empty directory</emphasis>. (See
+ "Building and releasing packages" above). Then add a log
+ entry to <filename>debian/changelog</filename>, if it is not
+ already there, for example by running:
+ </para>
+ <para>
+ <programlisting>
+ debchange -v &p-version;-&p-status;-1 "New upstream version"
</programlisting>
- </para>
- <para>
- Then do FIXME.
- </para>
+ </para>
+ <para>
+ Then, run:
+ </para>
+ <para>
+ <programlisting>
+ dpkg-buildpackage -rfakeroot -us -uc -b
+</programlisting>
+ </para>
+ <para>
+ This will create
+ <filename>../privoxy_&p-version;-&p-status;-1_i386.deb</filename>
+ which can be uploaded. To upload the package to Sourceforge, simply
+ issue
+ </para>
+ <para>
+ <programlisting>
+ make debian-upload
+</programlisting>
+ </para>
</sect3>
<sect3 id="newrelease-macosx"><title>Mac OSX</title>
</para>
<para>
<programlisting>
-zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
+ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
</programlisting>
</para>
<para>
<sect3 id="newrelease-freebsd"><title>FreeBSD</title>
<para>
- Login to Sourceforge's compilefarm via ssh:
+ Login to Sourceforge's compile-farm via ssh:
</para>
<para>
<programlisting>
mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
include the
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
- location</ulink>, the release notes and the change log.
+ location</ulink>, the release notes and the Changelog. Also, post an
+ updated News item on the project page Sourceforge, and update the Home
+ page and docs linked from the Home page (see below).
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="webserver-update"><title>Update the Webserver</title>
<para>
- When updating the webserver, please follow these steps to make
- sure that no broken links, incosistent contents or permission
- problems will occur:
+ The webserver should be updated at least with each stable release. When
+ updating, please follow these steps to make sure that no broken links,
+ inconsistent contents or permission problems will occur (as it has many
+ times in the past!):
</para>
<para>
- If you have changed anything in the documentation source SGML files,
- do:
+ If you have changed anything in the stable-branch documentation source
+ SGML files, do:
</para>
<para>
<programlisting>
- make dok # (or make redkat-dok if make dok doesn't work for you)
+ make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
</programlisting>
</para>
<para>
That will generate <filename>doc/webserver/user-manual</filename>,
<filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
+ <filename>doc/webserver/faq</filename>,
+ <filename>doc/pdf/*.pdf</filename> and
<filename>doc/webserver/index.html</filename> automatically.
</para>
<para>
- If you changed the manual page source, generate
+ If you changed the manual page sources, generate
<filename>doc/webserver/man-page/privoxy-man-page.html</filename>
by running <quote><command>make man</command></quote>. (This is
- a separate target due to dependencies on some obscure perl scripts.
- See comments in <filename>GNUmakefile</filename>.)
+ a separate target due to dependencies on some obscure perl scripts
+ [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.)
</para>
<para>
If you want to add new files to the webserver, create them locally in
create new directories under <filename>doc/webserver</filename>).
</para>
<para>
- Next, commit any changes from the above steps to CVS. All set? Then do
+ Next, commit any changes from the above steps to CVS. All set?
+ If these are docs in the stable branch, then do:
</para>
<para>
<programlisting>
</para>
<para>
Please do <emphasis>NOT</emphasis> use any other means of transferring
- files to the webserver to avoid permission problems.
+ files to the webserver to avoid permission problems. Also, please do not
+ upload docs from development branches or versions. The publicly posted
+ docs should be in sync with the last official release.
</para>
</sect1>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 2.5 2002/09/26 21:50:39 hal9
+ Changes to reflect recent change in stable branch commit policy (hopefully
+ clearer now).
+
+ Revision 2.4 2002/09/26 05:57:14 hal9
+ Conditionally exclude 'this doc is evolving' comment in intro for non release
+ situations.
+
+ Revision 2.3 2002/09/05 02:27:59 hal9
+ Mention tested stable branch fixes in main trunk, as alternate to posting
+ patches.
+
+ Revision 2.2 2002/09/04 01:55:44 hal9
+ Migrating developer manual, and related sgml files from 3.0. Add additional
+ commentary on cvs, versioning, stable branches, and how to handle stable
+ branches in cvs.
+
+ Revision 1.46.2.8 2002/08/17 00:16:10 hal9
+ Add note on updating webserver for User-manual/CGI editor, which is version
+ dependent (and different from main UM link).
+
+ Revision 1.46.2.7 2002/08/14 17:29:25 hal9
+ Add small notes on post-release steps, and uploading docs to webserver.
+
+ Revision 1.46.2.6 2002/08/10 11:40:25 oes
+ Added disclaimer about probably being out-of-date and two small hints
+
+ Revision 1.46.2.5 2002/08/09 01:15:12 hal9
+ Added some notes on pre-release steps (test builds first, update ChangeLog).
+
+ Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd
+ Fixed a little formatting. Clarified debian section.
+
+ Revision 1.46.2.3 2002/05/28 04:32:45 hal9
+ Change hints on bundling index.html to privoxy-index.html
+
+ Revision 1.46.2.2 2002/05/26 17:04:24 hal9
+ -Spellcheck, very minor edits, and sync across branches
+
+ Revision 1.48 2002/05/26 12:48:31 roro
+ Add releasing information about Debian.
+
+ Revision 1.47 2002/05/26 04:55:11 mal0rd
+ Added debian-dist and debian-upload targets. Also documented usage.
+
+ Revision 1.46 2002/05/22 17:15:00 oes
+ Updated intro
+
+ Revision 1.45 2002/05/19 23:01:54 hal9
+ Add small section on general packaging guidelines (e.g. actions files must
+ be writable).
+
+ Revision 1.44 2002/05/15 03:55:17 hal9
+ Fix ulink -> link, and minor modification to release process section for
+ clarification.
+
Revision 1.43 2002/05/10 01:48:19 hal9
This is mostly proposed copyright/licensing additions and changes. Docs
are still GPL, but licensing and copyright are more visible. Also, copyright
projects / privoxy.git / blobdiff