+ <!-- ~~~~~ 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>
+ 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>
+ </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>
+
+ <sect2 id="beforerelease">
+ <title>Before the Release: Freeze</title>
+ <para>
+ The following <emphasis>must be done by one of the
+ developers</emphasis> prior to each new release.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <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. Announce the
+ freeze so that nobody will interfere with last minute changes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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>
+ <para>
+ 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>
+ <programlisting>
+ {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
+</programlisting>
+ </para>
+ <para>
+ Then change the version info in doc/webserver/actions/index.php,
+ line: '$required_actions_file_version = "A.B";'
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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>
+ <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>
+ </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>
+ </itemizedlist>
+ </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>
+
+ <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>
+
+ <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>
+
+ <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>
+
+ <warning>
+ <para>
+ Every significant release of Privoxy has included at least one
+ package that either had incorrect versions of files, missing files,
+ or incidental leftovers from a previous build process that gave
+ unknown numbers of users headaches to try to figure out what was
+ wrong. PLEASE, make sure you are using pristene sources, and are
+ following the prescribed process!
+ </para>
+ </warning>
+
+ <para>
+ Please find additional instructions for the source tarball and the
+ individual platform dependent binary packages below. And details
+ 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>