- <div class="SECT1">
- <h1 class="SECT1">
- <a name="NEWRELEASE">6. Releasing a New Version</a>
- </h1>
- <p>
- When we release versions of <span class="APPLICATION">Privoxy</span>,
- 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.
- </p>
- <p>
- So when releasing a new version, please adhere exactly to the
- procedure outlined in this chapter.
- </p>
- <p>
- The following programs are required to follow this process: <tt
- class="FILENAME">ncftpput</tt> (ncftp), <tt class="FILENAME">scp,
- ssh</tt> (ssh), <tt class="FILENAME">gmake</tt> (GNU's version of
- make), autoconf, cvs.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="VERSIONNUMBERS">6.1. Version numbers</a>
- </h2>
- <p>
- First you need to determine which version number the release will
- have. <span class="APPLICATION">Privoxy</span> version numbers
- consist of three numbers, separated by dots, like in X.Y.Z (e.g.
- 3.0.0), where:
- </p>
- <ul>
- <li>
- <p>
- 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 <span class=
- "APPLICATION">Junkbuster</span>, and 3 will be the first stable
- <span class="APPLICATION">Privoxy</span> release.
- </p>
- </li>
- <li>
- <p>
- 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 <span class="APPLICATION">Privoxy</span> 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.
- </p>
- </li>
- <li>
- <p>
- 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.
- </p>
- <p>
- 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 <tt class="LITERAL">0.0.0</tt>,
- during that period between releases when changes are being
- added. This is to denote that this code is <span class=
- "emphasis"><i class="EMPHASIS">not for release</i></span>. Then
- as the release nears, the version is bumped according: e.g. <tt
- class="LITERAL">3.0.1 -> 0.0.0 -> 3.0.2</tt>.
- </p>
- </li>
- </ul>
-
- <p>
- 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
- <tt class="LITERAL">3.0</tt>, 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 <span class=
- "emphasis"><i class="EMPHASIS">before</i></span> committing to a
- stable branch!
- </p>
- <p>
- 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, <span
- class="emphasis"><i class="EMPHASIS">and</i></span> the stable
- release branch, which is <tt class="LITERAL">v_3_0_branch</tt> at
- the moment).
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="BEFORERELEASE">6.2. Before the Release: Freeze</a>
- </h2>
- <p>
- The following <span class="emphasis"><i class="EMPHASIS">must be
- done by one of the developers</i></span> prior to each new release.
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- Make sure that everybody who has worked on the code in the last
- couple of days has had a chance to yell <span class=
- "QUOTE">"no!"</span> in case they have pending changes/fixes in
- their pipelines. Announce the freeze so that nobody will
- interfere with last minute changes.
- </p>
- </li>
- <li>
- <p>
- Increment the version number (point from odd to even in
- development branches!) in <tt class=
- "FILENAME">configure.in</tt>. (RPM spec files will need to be
- incremented as well.)
- </p>
- </li>
- <li>
- <p>
- If <tt class="FILENAME">default.action</tt> 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:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="90%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
-</pre>
- </td>
- </tr>
- </table>
-
- <p>
- Then change the version info in
- doc/webserver/actions/index.php, line:
- '$required_actions_file_version = "A.B";'
- </p>
- </li>
- <li>
- <p>
- 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. <tt class=
- "FILENAME">config</tt>, 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.
- </p>
- </li>
- <li>
- <p>
- The <i class="CITETITLE">User Manual</i> 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 <i
- class="CITETITLE">User Manual</i> link from the main page since
- we need to keep manuals for various versions available). The
- CGI pages will link to something like <tt class=
- "LITERAL">http://privoxy.org/$(VERSION)/user-manual/</tt>. 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.
- </p>
- </li>
- <li>
- <p>
- All developers should look at the <tt class=
- "FILENAME">ChangeLog</tt> and make sure noteworthy changes are
- referenced.
- </p>
- </li>
- <li>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Commit all files
- that were changed in the above steps!</i></span>
- </p>
- </li>
- <li>
- <p>
- Tag all files in CVS with the version number with <span class=
- "QUOTE">"<b class="COMMAND">cvs tag v_X_Y_Z</b>"</span>. Don't
- use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
- </p>
- </li>
- <li>
- <p>
- If the release was in a development branch, increase the point
- version from even to odd (X.Y.(Z+1)) again in <tt class=
- "FILENAME">configure.in</tt> and commit your change.
- </p>
- </li>
- <li>
- <p>
- On the webserver, copy the user manual to a new top-level
- directory called <tt class="FILENAME">X.Y.Z</tt>. 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 <tt class=
- "FILENAME">X.Y.(Z-1)</tt> to <tt class="FILENAME">X.Y.Z</tt>
- and <tt class="FILENAME">X.Y.(Z+1)</tt> to <tt class=
- "FILENAME">.</tt> (i.e. dot).
- </p>
- </li>
- </ul>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="THERELEASE">6.3. Building and Releasing the Packages</a>
- </h2>
- <p>
- 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.
- </p>
- <p>
- For <span class="emphasis"><i class="EMPHASIS">all</i></span> types
- of packages, including the source tarball, <span class=
- "emphasis"><i class="EMPHASIS">you must make sure that you build
- from clean sources by exporting the right version from CVS into an
- empty directory</i></span> (just press return when asked for a
- password):
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="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
-</pre>
- </td>
- </tr>
- </table>
-
- <p>
- <span class="emphasis"><i class="EMPHASIS">Do NOT change</i></span>
- 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.
- </p>
- <div class="WARNING">
- <table class="WARNING" border="1" width="100%">
- <tr>
- <td align="CENTER">
- <b>Warning</b>
- </td>
- </tr>
- <tr>
- <td align="LEFT">
- <p>
- 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!
- </p>
- </td>
- </tr>
- </table>
- </div>
- <p>
- 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.
- </p>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="PACK-GUIDELINES">6.3.1. Note on Privoxy Packaging</a>
- </h3>
- <p>
- Please keep these general guidelines in mind when putting
- together your package. These apply to <span class="emphasis"><i
- class="EMPHASIS">all</i></span> platforms!
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- <span class="APPLICATION">Privoxy</span> <span class=
- "emphasis"><i class="EMPHASIS">requires</i></span> write
- access to: all <tt class="FILENAME">*.action</tt> files, all
- logfiles, and the <tt class="FILENAME">trust</tt> file. You
- will need to determine the best way to do this for your
- platform.
- </p>
- </li>
- <li>
- <p>
- Please include up to date documentation. At a bare minimum:
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">LICENSE</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">README</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">AUTHORS</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">man page</tt> (top-level
- directory, Unix-like platforms only)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">The User Manual</tt>
- (doc/webserver/user-manual/)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">FAQ</tt> (doc/webserver/faq/)
- </td>
- </tr>
- </tbody>
- </table>
- <p>
- Also suggested: <tt class="FILENAME">Developer Manual</tt>
- (doc/webserver/developer-manual) and <tt class=
- "FILENAME">ChangeLog</tt> (top-level directory). <tt class=
- "FILENAME">FAQ</tt> and the manuals are HTML docs. There are
- also text versions in <tt class="FILENAME">doc/text/</tt>
- which could conceivably also be included.
- </p>
- <p>
- The documentation has been designed such that the manuals are
- linked to each other from parallel directories, and should be
- packaged that way. <tt class=
- "FILENAME">privoxy-index.html</tt> can also be included and
- can serve as a focal point for docs and other links of
- interest (and possibly renamed to <tt class=
- "FILENAME">index.html</tt>). 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 <tt class=
- "FILENAME">doc/webserver/man-page/privoxy-man-page.html</tt>,
- and should be included along with the manuals. There is also
- a css stylesheets that can be included for better
- presentation: <tt class="FILENAME">p_doc.css</tt>. This
- should be in the same directory with <tt class=
- "FILENAME">privoxy-index.html</tt>, (i.e. one level up from
- the manual directories).
- </p>
- </li>
- <li>
- <p>
- <tt class="FILENAME">user.action</tt> and <tt class=
- "FILENAME">user.filter</tt> are designed for local
- preferences. Make sure these do not get overwritten! <tt
- class="FILENAME">config</tt> should not be overwritten
- either. This has especially important configuration data in
- it. <tt class="FILENAME">trust</tt> should be left in tact as
- well.
- </p>
- </li>
- <li>
- <p>
- Other configuration files (<tt class=
- "FILENAME">default.action</tt> and <tt class=
- "FILENAME">default.filter</tt>) 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.
- </p>
- </li>
- <li>
- <p>
- Please check platform specific notes in this doc, if you
- haven't done <span class="QUOTE">"Privoxy"</span> 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).
- </p>
- </li>
- <li>
- <p>
- Packagers should do a <span class="QUOTE">"clean"</span>
- 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.
- </p>
- </li>
- </ul>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-TARBALL">6.3.2. Source Tarball</a>
- </h3>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- cd current
- autoheader && autoconf && ./configure
-</pre>
- </td>
- </tr>
- </table>
-
- <p>
- Then do:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- make tarball-dist
-</pre>
- </td>
- </tr>
- </table>
-
- <p>
- To upload the package to Sourceforge, simply issue
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- make tarball-upload
-</pre>
- </td>
- </tr>
- </table>
-
- <p>
- Go to the displayed URL and release the file publicly on
- Sourceforge. For the change log field, use the relevant section
- of the <tt class="FILENAME">ChangeLog</tt> file.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-RPM">6.3.3. SuSE, Conectiva or Red Hat
- RPM</a>
- </h3>
- <p>
- In following text, replace <tt class=
- "REPLACEABLE"><i>dist</i></tt> with either <span class=
- "QUOTE">"rh"</span> for Red Hat or <span class=
- "QUOTE">"suse"</span> for SuSE.
- </p>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above).
- </p>
- <p>
- As the only exception to not changing anything after export from
- CVS, now examine the file <tt class="FILENAME">privoxy-</tt><tt
- class="REPLACEABLE"><i>dist</i></tt><tt class=
- "FILENAME">.spec</tt> 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 <tt class=
- "REPLACEABLE"><i>dist</i></tt> which is built from version X.Y.Z.
- Check the <a href=
- "https://sourceforge.net/project/showfiles.php?group_id=11118"
- target="_top">file list</a> if unsure. Else, it must be set to
- the highest already available RPM release number for that version
- plus one.
- </p>
- <p>
- Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">