By: Privoxy Developers
-$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $
+$Id: developer-manual.sgml,v 1.39 2002/05/02 15:08:25 oes Exp $
The developer manual gives the users information on how to help the developer
team. It provides guidance on coding, testing, documentation and other issues.
8. Releasing a New Version
- 8.1. Before the Release
- 8.2. Building and Releasing the Packages
+ 8.1. Version numbers
+ 8.2. Before the Release: Freeze
+ 8.3. Building and Releasing the Packages
- 8.2.1. Source Tarball
- 8.2.2. SuSE or Red Hat
- 8.2.3. OS/2
- 8.2.4. Solaris
- 8.2.5. Windows
- 8.2.6. Debian
- 8.2.7. Mac OSX
- 8.2.8. FreeBSD
- 8.2.9. HP-UX 11
- 8.2.10. Amiga OS
- 8.2.11. AIX
+ 8.3.1. Source Tarball
+ 8.3.2. SuSE or Red Hat RPM
+ 8.3.3. OS/2
+ 8.3.4. Solaris
+ 8.3.5. Windows
+ 8.3.6. Debian
+ 8.3.7. Mac OSX
+ 8.3.8. FreeBSD
+ 8.3.9. HP-UX 11
+ 8.3.10. Amiga OS
+ 8.3.11. AIX
- 8.3. Uploading and Releasing Your Package
- 8.4. After the Release
+ 8.4. Uploading and Releasing Your Package
+ 8.5. After the Release
9. Update the Webserver
10. Contacting the developers, Bug Reporting and Feature Requests
Some common elements that you likely will use:
-<para></para>, paragraph delimiter. Most text needs to be within paragraph
-elements (there are some exceptions).
-<emphasis></emphasis>, the stylesheets make this italics.
-<filename></filename>, files and directories.
-<command></command>, command examples.
-<literallayout></literallayout>, like <pre>, more or less.
-<itemizedlist></itemizedlist>, list with bullets.
-<listitem></listitem>, member of the above.
-<screen></screen>, screen output, implies <literallayout>.
-<ulink url="example.com"></ulink>, like HTML <a> tag.
-<quote></quote>, for, doh, quoting text.
+, paragraph delimiter. Most text needs to be within paragraph elements (there
+are some exceptions).
+, the stylesheets make this italics.
+, files and directories.
+, command examples.
+, like
+, more or less.
+, list with bullets.
+, member of the above.
+, screen output, implies .
+, like HTML tag.
+, for, doh, quoting text.
Look at any of the existing docs for examples of all these and more.
Example:
-#include <iostream.h> /* This is not a local include */
+#include /* This is not a local include */
#include "config.h" /* This IS a local include */
Exception:
/* This is not a local include, but requires a path element. */
-#include <sys/fileName.h>
+#include
Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
This duplicates the #include "file.h" behavior.
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.39 2002/05/02 15:08:25 oes Exp $";
/*********************************************************************
*
* File : $Source$
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.39 2002/05/02 15:08:25 oes Exp $"
/*********************************************************************
*
* File : $Source$
The following programs are required to follow this process: ncftpput (ncftp),
scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
-In the following text, replace X, Y and Z with the actual version number (X =
-major, Y = minor, Z = point):
+-------------------------------------------------------------------------------
+
+8.1. Version numbers
+First you need to determine which version number the release will have. Privoxy
+version numbers consist of three numbers, separated by dots, like in X.Y.Z,
+where:
+
+ * 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
+ Junkbuster, and 3 will be the first stable Privoxy release.
+
+ * 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
+ which the further development of Privoxy 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 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.
+
+ * 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.
+
-------------------------------------------------------------------------------
-8.1. Before the Release
+8.2. Before the Release: Freeze
The following must be done by one of the developers prior to each new release.
* Make sure that everybody who has worked on the code in the last couple of
days has had a chance to yell "no!" in case they have pending changes/fixes
- in their pipelines.
+ in their pipelines. Announce the freeze so that nobody will interfere with
+ last minute changes.
- * Increment the version number and increase or reset the RPM release number
- in configure.in as appropriate.
+ * Increment the version number (point from odd to even in development
+ branches!) in configure.in.
- * If the default actionsfile has changed since last release, bump up its
- version info in this line:
+ * If default.action 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:
{+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
'$required_actions_file_version = "A.B";'
* If the HTML documentation is not in sync with the SGML sources you need to
- regenerate it. (If in doubt, just do it.) See the Section "Updating the
- webserver" in this manual for details.
+ regenerate and upload it to the webserver. (If in doubt, just do it.) See
+ the Section "Updating the webserver" in this manual for details.
* Commit all files that were changed in the above steps!
* Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't
use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
+ * If the release was in a development branch, increase the point version from
+ even to odd (X.Y.(Z+1)) again in configure.in and commit your change.
+
+ * On the webserver, copy the user manual to a new top-level directory called
+ X.Y.Z. 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 X.Y.(Z-1) to X.Y.Z and X.Y.
+ (Z+1) to . (i.e. dot).
+
-------------------------------------------------------------------------------
-8.2. Building and Releasing the Packages
+8.3. Building and Releasing the Packages
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.
-------------------------------------------------------------------------------
-8.2.1. Source Tarball
+8.3.1. Source Tarball
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then run:
-------------------------------------------------------------------------------
-8.2.2. SuSE or Red Hat
+8.3.2. SuSE or Red Hat RPM
+
+In following text, replace dist with either "rh" for Red Hat or "suse" for
+SuSE.
First, make sure that you have freshly exported the right version into an empty
-directory. (See "Building and releasing packages" above). Then run:
+directory. (See "Building and releasing packages" above).
+
+As the only exception to not changing anything after export from CVS, now
+examine the file privoxy-dist.spec 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 dist which is built from version X.Y.Z. Check the file list if unsure.
+Else, it must be set to the highest already available RPM release number for
+that version plus one.
+
+Then run:
cd current
autoheader && autoconf && ./configure
Then do
- make suse-dist (or make redhat-dist)
+ make dist-dist
To upload the package to Sourceforge, simply issue
- make suse-upload (or make redhat-upload)
+ make dist-upload rpm_packagerev
-Go to the displayed URL and release the file publicly on Sourceforge. Use the
-release notes and çhange log from the source tarball package.
+where rpm_packagerev 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.
-------------------------------------------------------------------------------
-8.2.3. OS/2
+8.3.3. OS/2
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then get the OS/2
-------------------------------------------------------------------------------
-8.2.4. Solaris
+8.3.4. Solaris
Login to Sourceforge's compilefarm via ssh:
-------------------------------------------------------------------------------
-8.2.5. Windows
+8.3.5. Windows
You should ensure you have the latest version of Cygwin (from http://
www.cygwin.com/). Run the following commands from within a Cygwin bash shell.
-------------------------------------------------------------------------------
-8.2.6. Debian
+8.3.6. Debian
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then, run:
-------------------------------------------------------------------------------
-8.2.7. Mac OSX
+8.3.7. Mac OSX
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then get the Mac OSX
-------------------------------------------------------------------------------
-8.2.8. FreeBSD
+8.3.8. FreeBSD
Login to Sourceforge's compilefarm via ssh:
-------------------------------------------------------------------------------
-8.2.9. HP-UX 11
+8.3.9. HP-UX 11
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then run:
-------------------------------------------------------------------------------
-8.2.10. Amiga OS
+8.3.10. Amiga OS
First, make sure that you have freshly exported the right version into an empty
directory. (See "Building and releasing packages" above). Then run:
-------------------------------------------------------------------------------
-8.2.11. AIX
+8.3.11. AIX
Login to Sourceforge's compilefarm via ssh:
-------------------------------------------------------------------------------
-8.3. Uploading and Releasing Your Package
+8.4. Uploading and Releasing Your Package
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:
* password: ijbswa-developers@lists.sourceforge.net
Once this done go to http://sourceforge.net/project/admin/editpackages.php?
-group_id=11118, making sure you are logged in. Find the your target platform in
-the second column, and click Add Release. You will then need to create a new
+group_id=11118, making sure you are logged in. Find your target platform in the
+second column, and click Add Release. You will then need to create a new
release for your package, using the format of $VERSION ($CODE_STATUS), e.g.
2.9.14 (beta).
-------------------------------------------------------------------------------
-8.4. After the Release
+8.5. After the Release
When all (or: most of the) packages have been uploaded and made available, send
an email to the announce mailing list, Subject: "Version X.Y.Z available for
By: Privoxy Developers
-$Id: user-manual.sgml,v 1.99 2002/04/28 16:59:05 swa Exp $
+$Id: user-manual.sgml,v 1.100 2002/04/29 03:05:55 hal9 Exp $
The user manual gives users information on how to install, configure and use
Privoxy.
without Internet access. You will see the following section:
Privoxy Menu
- ? View & change the current configuration
- ? View the source code version numbers
- ? View the request headers.
- ? Look up which actions apply to a URL and why
- ? Toggle Privoxy on or off
+ ?? View & change the current configuration
+ ?? View the source code version numbers
+ ?? View the request headers.
+ ?? Look up which actions apply to a URL and why
+ ?? Toggle Privoxy on or off
This should be self-explanatory. Note the first item leads to an editor for the
And finally we pull it all together in the bottom section and summarize how
Privoxy is applying all its "actions" to "google.com":
- Final results:
+ Final results:
-add-header -block +deanimate-gifs{last} -downgrade-http-version -fast-redirects
-filter{popups} -filter{fun} -filter{shockwave-flash} -filter{crude-parental}
+filter{html-annoyances} +filter{js-annoyances} +filter{content-cookies}
Now another example, "ad.doubleclick.net":
- { +block +handle-as-image }
+ { +block +handle-as-image }
.ad.doubleclick.net
{ +block +handle-as-image }
One last example. Let's try "http://www.rhapsodyk.net/adsl/HOWTO/". This one is
giving us problems. We are getting a blank page. Hmmm...
- Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
+ Matches for http://www.rhapsodyk.net/adsl/HOWTO/:
{ -add-header -block +deanimate-gifs -downgrade-http-version +fast-redirects
+filter{html-annoyances} +filter{js-annoyances} +filter{kill-popups}
explicitly does not block ("{-block}") paths with "adsl". There are various
ways to handle such exceptions. Example:
- { -block }
+ { -block }
/adsl
Now the page displays ;-) Be sure to flush your browser's caches when making
But now what about a situation where we get no explicit matches like we did
with:
- { +block +handle-as-image }
+ { +block +handle-as-image }
/ads
That actually was very telling and pointed us quickly to where the problem was.
cause would be one of the "{+filter}" actions. Try adding the URL for the site
to one of aliases that turn off "+filter":
- {shop}
+ {shop}
.quietpc.com
.worldpay.com # for quietpc.com
.jungle.com
"{shop}" is an "alias" that expands to "{ -filter -session-cookies-only }". Or
you could do your own exception to negate filtering:
- {-filter}
+ {-filter}
.forbes.com
This would probably be most appropriately put in user.action, for local site
>gmake</TT
> (GNU's version of make), autoconf, cvs.
</P
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="VERSIONNUMBERS"
+>8.1. Version numbers</A
+></H2
><P
-> In the following text, replace X, Y and Z with the actual version number
- (X = major, Y = minor, Z = point):
+> 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, where:
+ <P
+></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 bugfixes 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 inrcemented. 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
+></LI
+></UL
+>
</P
+></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="BEFORERELEASE"
->8.1. Before the Release</A
+>8.2. Before the Release: Freeze</A
></H2
><P
> The following <I
CLASS="QUOTE"
>"no!"</SPAN
> 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.
</P
></LI
><LI
><P
-> Increment the version number and increase or reset the RPM release number
- in <TT
+> Increment the version number (point from odd to even in development
+ branches!) in <TT
CLASS="FILENAME"
>configure.in</TT
-> as appropriate.
+>.
</P
></LI
><LI
><P
-> If the default <TT
+> If <TT
CLASS="FILENAME"
->actionsfile</TT
+>default.action</TT
> has changed since last
- release, bump up its version info in this line:
+ release (i.e. software release or standalone actions file release),
+ bump up its version info to A.B in this line:
</P
><P
>
><LI
><P
> If the HTML documentation is not in sync with the SGML sources
- you need to regenerate it. (If in doubt, just do it.) See the
- Section "Updating the webserver" in this manual for details.
+ 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.
</P
></LI
><LI
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
>
</P
CLASS="SECT2"
><A
NAME="THERELEASE"
->8.2. Building and Releasing the Packages</A
+>8.3. Building and Releasing the Packages</A
></H2
><P
> Now the individual packages can be built and released. Note that for
CLASS="SECT3"
><A
NAME="NEWRELEASE-TARBALL"
->8.2.1. Source Tarball</A
+>8.3.1. Source Tarball</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-RPM"
->8.2.2. SuSE or Red Hat</A
+>8.3.2. SuSE 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, <I
CLASS="EMPHASIS"
>make sure that you have freshly exported the right
version into an empty directory</I
>. (See "Building and releasing
- packages" above). Then run:
+ 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="http://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
> <TABLE
><TD
><PRE
CLASS="PROGRAMLISTING"
-> make suse-dist (or make redhat-dist)</PRE
+> make <TT
+CLASS="REPLACEABLE"
+><I
+>dist</I
+></TT
+>-dist</PRE
></TD
></TR
></TABLE
><TD
><PRE
CLASS="PROGRAMLISTING"
-> make suse-upload (or make redhat-upload)</PRE
+> make <TT
+CLASS="REPLACEABLE"
+><I
+>dist</I
+></TT
+>-upload <TT
+CLASS="REPLACEABLE"
+><I
+>rpm_packagerev</I
+></TT
+></PRE
></TD
></TR
></TABLE
>
</P
><P
-> Go to the displayed URL and release the file publicly on Sourceforge.
- Use the release notes and çhange log from the source tarball package.
+> where <TT
+CLASS="REPLACEABLE"
+><I
+>rpm_packagerev</I
+></TT
+> 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.
</P
></DIV
><DIV
CLASS="SECT3"
><A
NAME="NEWRELEASE-OS2"
->8.2.3. OS/2</A
+>8.3.3. OS/2</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-SOLARIS"
->8.2.4. Solaris</A
+>8.3.4. Solaris</A
></H3
><P
> Login to Sourceforge's compilefarm via ssh:
CLASS="SECT3"
><A
NAME="NEWRELEASE-WINDOWS"
->8.2.5. Windows</A
+>8.3.5. Windows</A
></H3
><P
> You should ensure you have the latest version of Cygwin (from
CLASS="SECT3"
><A
NAME="NEWRELEASE-DEBIAN"
->8.2.6. Debian</A
+>8.3.6. Debian</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-MACOSX"
->8.2.7. Mac OSX</A
+>8.3.7. Mac OSX</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-FREEBSD"
->8.2.8. FreeBSD</A
+>8.3.8. FreeBSD</A
></H3
><P
> Login to Sourceforge's compilefarm via ssh:
CLASS="SECT3"
><A
NAME="NEWRELEASE-HPUX"
->8.2.9. HP-UX 11</A
+>8.3.9. HP-UX 11</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-AMIGA"
->8.2.10. Amiga OS</A
+>8.3.10. Amiga OS</A
></H3
><P
> First, <I
CLASS="SECT3"
><A
NAME="NEWRELEASE-AIX"
->8.2.11. AIX</A
+>8.3.11. AIX</A
></H3
><P
> Login to Sourceforge's compilefarm via ssh:
CLASS="SECT2"
><A
NAME="RELEASING"
->8.3. Uploading and Releasing Your Package</A
+>8.4. Uploading and Releasing Your Package</A
></H2
><P
> After the package is ready, it is time to upload it
- to SourceForge, and go through the release steps. The upload
+ to SourceForge, and go through the release steps. The upload
is done via FTP:
</P
><P
CLASS="SECT2"
><A
NAME="AFTERRELEASE"
->8.4. After the Release</A
+>8.5. After the Release</A
></H2
><P
> When all (or: most of the) packages have been uploaded and made available,
projects / privoxy.git / commitdiff