Privoxy Developer Manual
-By: Privoxy Developers
+Copyright © 2001, 2002 by Privoxy Developers
-$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $
+$Id: developer-manual.sgml,v 1.42 2002/05/05 20:26:02 hal9 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.
-Privoxy is a web proxy with advanced filtering capabilities for protecting
-privacy, filtering web page content, managing cookies, controlling access, and
-removing ads, banners, pop-ups and other obnoxious Internet junk. Privoxy has a
-very flexible configuration and can be customized to suit individual needs and
-tastes. Privoxy has application for both stand-alone systems and multi-user
-networks.
-
-Privoxy is based on the code of the Internet Junkbuster (tm). Junkbuster was
-originally written by Junkbusters Corporation, and was released as free
-open-source software under the GNU GPL. Stefan Waldherr made many improvements,
-and started the SourceForge project to continue development.
-
-Privoxy continues the Junkbuster tradition, but adds many refinements,
-enhancements and new features.
-
You can find the latest version of the this manual at http://www.privoxy.org/
developer-manual/. Please see the Contact section on how to contact the
developers.
-------------------------------------------------------------------------------
Table of Contents
-
1. Introduction
-3. Quickstart to Privoxy Development
-4. Documentation Guidelines
- 4.1. Quickstart to Docbook and SGML
- 4.2. Privoxy Documentation Style
- 4.3. Privoxy Custom Entities
+ 1.1. Quickstart to Privoxy Development
+
+2. The CVS Repository
+
+ 2.1. Access to CVS
+ 2.2. CVS Commit Guideline
+ 2.3. Discussing Changes First
-5. Coding Guidelines
+3. Documentation Guidelines
- 5.1. Introduction
- 5.2. Using Comments
+ 3.1. Quickstart to Docbook and SGML
+ 3.2. Privoxy Documentation Style
+ 3.3. Privoxy Custom Entities
+
+4. Coding Guidelines
+
+ 4.1. Introduction
+ 4.2. Using Comments
- 5.2.1. Comment, Comment, Comment
- 5.2.2. Use blocks for comments
- 5.2.3. Keep Comments on their own line
- 5.2.4. Comment each logical step
- 5.2.5. Comment All Functions Thoroughly
- 5.2.6. Comment at the end of braces if the content is more than one
+ 4.2.1. Comment, Comment, Comment
+ 4.2.2. Use blocks for comments
+ 4.2.3. Keep Comments on their own line
+ 4.2.4. Comment each logical step
+ 4.2.5. Comment All Functions Thoroughly
+ 4.2.6. Comment at the end of braces if the content is more than one
screen length
- 5.3. Naming Conventions
+ 4.3. Naming Conventions
- 5.3.1. Variable Names
- 5.3.2. Function Names
- 5.3.3. Header file prototypes
- 5.3.4. Enumerations, and #defines
- 5.3.5. Constants
+ 4.3.1. Variable Names
+ 4.3.2. Function Names
+ 4.3.3. Header file prototypes
+ 4.3.4. Enumerations, and #defines
+ 4.3.5. Constants
- 5.4. Using Space
+ 4.4. Using Space
- 5.4.1. Put braces on a line by themselves.
- 5.4.2. ALL control statements should have a block
- 5.4.3. Do not belabor/blow-up boolean expressions
- 5.4.4. Use white space freely because it is free
- 5.4.5. Don't use white space around structure operators
- 5.4.6. Make the last brace of a function stand out
- 5.4.7. Use 3 character indentions
+ 4.4.1. Put braces on a line by themselves.
+ 4.4.2. ALL control statements should have a block
+ 4.4.3. Do not belabor/blow-up boolean expressions
+ 4.4.4. Use white space freely because it is free
+ 4.4.5. Don't use white space around structure operators
+ 4.4.6. Make the last brace of a function stand out
+ 4.4.7. Use 3 character indentions
- 5.5. Initializing
+ 4.5. Initializing
- 5.5.1. Initialize all variables
+ 4.5.1. Initialize all variables
- 5.6. Functions
+ 4.6. Functions
- 5.6.1. Name functions that return a boolean as a question.
- 5.6.2. Always specify a return type for a function.
- 5.6.3. Minimize function calls when iterating by using variables
- 5.6.4. Pass and Return by Const Reference
- 5.6.5. Pass and Return by Value
- 5.6.6. Names of include files
- 5.6.7. Provide multiple inclusion protection
- 5.6.8. Use `extern "C"` when appropriate
- 5.6.9. Where Possible, Use Forward Struct Declaration Instead of
+ 4.6.1. Name functions that return a boolean as a question.
+ 4.6.2. Always specify a return type for a function.
+ 4.6.3. Minimize function calls when iterating by using variables
+ 4.6.4. Pass and Return by Const Reference
+ 4.6.5. Pass and Return by Value
+ 4.6.6. Names of include files
+ 4.6.7. Provide multiple inclusion protection
+ 4.6.8. Use `extern "C"` when appropriate
+ 4.6.9. Where Possible, Use Forward Struct Declaration Instead of
Includes
- 5.7. General Coding Practices
+ 4.7. General Coding Practices
- 5.7.1. Turn on warnings
- 5.7.2. Provide a default case for all switch statements
- 5.7.3. Try to avoid falling through cases in a switch statement.
- 5.7.4. Use 'long' or 'short' Instead of 'int'
- 5.7.5. Don't mix size_t and other types
- 5.7.6. Declare each variable and struct on its own line.
- 5.7.7. Use malloc/zalloc sparingly
- 5.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
+ 4.7.1. Turn on warnings
+ 4.7.2. Provide a default case for all switch statements
+ 4.7.3. Try to avoid falling through cases in a switch statement.
+ 4.7.4. Use 'long' or 'short' Instead of 'int'
+ 4.7.5. Don't mix size_t and other types
+ 4.7.6. Declare each variable and struct on its own line.
+ 4.7.7. Use malloc/zalloc sparingly
+ 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
'free'
- 5.7.9. Add loaders to the `file_list' structure and in order
- 5.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
+ 4.7.9. Add loaders to the `file_list' structure and in order
+ 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
- 5.8. Addendum: Template for files and function comment blocks:
+ 4.8. Addendum: Template for files and function comment blocks:
-6. Version Control Guidelines
-7. Testing Guidelines
+5. Testing Guidelines
- 7.1. Testplan for releases
- 7.2. Test reports
+ 5.1. Testplan for releases
+ 5.2. Test reports
-8. Releasing a new version
+6. Releasing a New Version
- 8.1. Before the Release
- 8.2. Update the webserver
- 8.3. SuSE or Red Hat
- 8.4. OS/2
- 8.5. Solaris
- 8.6. Windows
- 8.7. Debian
- 8.8. Mac OSX
- 8.9. FreeBSD
- 8.10. Tarball
- 8.11. HP-UX 11
- 8.12. Amiga OS
- 8.13. AIX
+ 6.1. Version numbers
+ 6.2. Before the Release: Freeze
+ 6.3. Building and Releasing the Packages
+
+ 6.3.1. Source Tarball
+ 6.3.2. SuSE or Red Hat RPM
+ 6.3.3. OS/2
+ 6.3.4. Solaris
+ 6.3.5. Windows
+ 6.3.6. Debian
+ 6.3.7. Mac OSX
+ 6.3.8. FreeBSD
+ 6.3.9. HP-UX 11
+ 6.3.10. Amiga OS
+ 6.3.11. AIX
+
+ 6.4. Uploading and Releasing Your Package
+ 6.5. After the Release
-9. Contacting the developers, Bug Reporting and Feature Requests
-10. Copyright and History
+7. Update the Webserver
+8. Contacting the developers, Bug Reporting and Feature Requests
- 10.1. Copyright
- 10.2. History
+ 8.1. Get Support
+ 8.2. Report bugs
+ 8.3. Request new features
+ 8.4. Report ads or other filter problems
+ 8.5. Other
-11. See also
-
--------------------------------------------------------------------------------
+9. Privoxy Copyright, License and History
+
+ 9.1. License
+ 9.2. History
+
+10. See also
1. Introduction
-------------------------------------------------------------------------------
-3. Quickstart to Privoxy Development
+1.1. Quickstart to Privoxy Development
You'll need an account on Sourceforge to support our development. Mail your ID
to the list and wait until a project manager has added you.
-For the time being (read, this section is under construction), please note the
-following guidelines for changing stuff in the code. If it is
+For the time being (read, this section is under construction), please refer to
+the extensive comments in the source code.
+
+-------------------------------------------------------------------------------
+
+2. The CVS Repository
+
+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.
+
+-------------------------------------------------------------------------------
+
+2.1. Access to CVS
+
+The project's CVS repository is hosted on SourceForge. Please refer to the
+chapters 6 and 7 in SF's site documentation for the technical access details
+for your operating system. For historical reasons, the CVS server is called
+cvs.ijbswa.sourceforge.net, the repository is called ijbswa, and the source
+tree module is called current.
+
+-------------------------------------------------------------------------------
+
+2.2. CVS Commit Guideline
+
+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:
+
+ * Never (read: never, ever) be tempted to commit that small change without
+ testing it thoroughly first. When we're close to a public release, ask a
+ fellow developer to review your changes.
+
+ * Your commit message should give a concise overview of what you changed (no
+ big details) and why you changed it Just check previous messages for good
+ examples.
+
+ * Don't use the same message on multiple files, unless it equally applies to
+ all those files.
+
+ * 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. If
+ necessary, prepare the commit messages in advance.
+
+ * 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).
+
+-------------------------------------------------------------------------------
+
+2.3. Discussing Changes First
+
+We don't have a too formal policy on this, just use common sense. Hints: If it
+is..
- 1. A bugfix / clean-up / cosmetic thing: shoot
+ 1. ..a bugfix / clean-up / cosmetic thing: shoot
- 2. A new feature that can be turned off: shoot
+ 2. ..a new feature that can be turned off: shoot
- 3. A clear improvement w/o side effects on other parts of the code: shoot
+ 3. ..a clear improvement w/o side effects on other parts of the code: shoot
- 4. A matter of taste: ask the list
+ 4. ..a matter of taste: ask the list
- 5. A major redesign of some part of the code: ask the list
+ 5. ..a major redesign of some part of the code: ask the list
Note that near a major public release, we get a bit more cautious - if unsure,
-it doesn't hurt to ask first.
+it doesn't hurt to ask first. There is always the possibility to submit a patch
+to the patches tracker instead.
-------------------------------------------------------------------------------
-4. Documentation Guidelines
+3. Documentation Guidelines
All formal documents are maintained in Docbook SGML and located in the doc/
source/* directory. You will need Docbook, the Docbook DTD's and the Docbook
-------------------------------------------------------------------------------
-4.1. Quickstart to Docbook and SGML
+3.1. Quickstart to Docbook and SGML
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
Some common elements that you likely will use:
-, 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.
+<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.
Look at any of the existing docs for examples of all these and more.
+You might also find "Writing Documentation Using DocBook - A Crash Course"
+useful.
+
-------------------------------------------------------------------------------
-4.2. Privoxy Documentation Style
+3.2. Privoxy Documentation Style
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
-------------------------------------------------------------------------------
-4.3. Privoxy Custom Entities
+3.3. Privoxy Custom Entities
Privoxy documentation is using a number of customized "entities" to facilitate
documentation maintenance.
* Commonly used "internal entities":
- p-version: the Privoxy version string, e.g. "2.9.14".
+ p-version: the Privoxy version string, e.g. "2.9.15".
p-status: the project status, either "alpha", "beta", or "stable".
p-not-stable: use to conditionally include text in "not stable" releases
(e.g. "beta").
-------------------------------------------------------------------------------
-5. Coding Guidelines
+4. Coding Guidelines
-5.1. Introduction
+4.1. Introduction
This set of standards is designed to make our lives easier. It is developed
with the simple goal of helping us keep the "new and improved Privoxy"
-------------------------------------------------------------------------------
-5.2. Using Comments
+4.2. Using Comments
-5.2.1. Comment, Comment, Comment
+4.2.1. Comment, Comment, Comment
Explanation:
-------------------------------------------------------------------------------
-5.2.2. Use blocks for comments
+4.2.2. Use blocks for comments
Explanation:
-------------------------------------------------------------------------------
-5.2.3. Keep Comments on their own line
+4.2.3. Keep Comments on their own line
Explanation:
-------------------------------------------------------------------------------
-5.2.4. Comment each logical step
+4.2.4. Comment each logical step
Explanation:
-------------------------------------------------------------------------------
-5.2.5. Comment All Functions Thoroughly
+4.2.5. Comment All Functions Thoroughly
Explanation:
-------------------------------------------------------------------------------
-5.2.6. Comment at the end of braces if the content is more than one screen
+4.2.6. Comment at the end of braces if the content is more than one screen
length
Explanation:
-------------------------------------------------------------------------------
-5.3. Naming Conventions
+4.3. Naming Conventions
-5.3.1. Variable Names
+4.3.1. Variable Names
Explanation:
-------------------------------------------------------------------------------
-5.3.2. Function Names
+4.3.2. Function Names
Explanation:
-------------------------------------------------------------------------------
-5.3.3. Header file prototypes
+4.3.3. Header file prototypes
Explanation:
-------------------------------------------------------------------------------
-5.3.4. Enumerations, and #defines
+4.3.4. Enumerations, and #defines
Explanation:
-------------------------------------------------------------------------------
-5.3.5. Constants
+4.3.5. Constants
Explanation:
-------------------------------------------------------------------------------
-5.4. Using Space
+4.4. Using Space
-5.4.1. Put braces on a line by themselves.
+4.4.1. Put braces on a line by themselves.
Explanation:
-------------------------------------------------------------------------------
-5.4.2. ALL control statements should have a block
+4.4.2. ALL control statements should have a block
Explanation:
-------------------------------------------------------------------------------
-5.4.3. Do not belabor/blow-up boolean expressions
+4.4.3. Do not belabor/blow-up boolean expressions
Example:
-------------------------------------------------------------------------------
-5.4.4. Use white space freely because it is free
+4.4.4. Use white space freely because it is free
Explanation:
-------------------------------------------------------------------------------
-5.4.5. Don't use white space around structure operators
+4.4.5. Don't use white space around structure operators
Explanation:
-------------------------------------------------------------------------------
-5.4.6. Make the last brace of a function stand out
+4.4.6. Make the last brace of a function stand out
Example:
-------------------------------------------------------------------------------
-5.4.7. Use 3 character indentions
+4.4.7. Use 3 character indentions
Explanation:
-------------------------------------------------------------------------------
-5.5. Initializing
+4.5. Initializing
-5.5.1. Initialize all variables
+4.5.1. Initialize all variables
Explanation:
-------------------------------------------------------------------------------
-5.6. Functions
+4.6. Functions
-5.6.1. Name functions that return a boolean as a question.
+4.6.1. Name functions that return a boolean as a question.
Explanation:
-------------------------------------------------------------------------------
-5.6.2. Always specify a return type for a function.
+4.6.2. Always specify a return type for a function.
Explanation:
-------------------------------------------------------------------------------
-5.6.3. Minimize function calls when iterating by using variables
+4.6.3. Minimize function calls when iterating by using variables
Explanation:
-------------------------------------------------------------------------------
-5.6.4. Pass and Return by Const Reference
+4.6.4. Pass and Return by Const Reference
Explanation:
-------------------------------------------------------------------------------
-5.6.5. Pass and Return by Value
+4.6.5. Pass and Return by Value
Explanation:
-------------------------------------------------------------------------------
-5.6.6. Names of include files
+4.6.6. Names of include files
Explanation:
Example:
-#include /* This is not a local include */
+#include <iostream.h> /* 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
+#include <sys/fileName.h>
Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
This duplicates the #include "file.h" behavior.
-------------------------------------------------------------------------------
-5.6.7. Provide multiple inclusion protection
+4.6.7. Provide multiple inclusion protection
Explanation:
-------------------------------------------------------------------------------
-5.6.8. Use `extern "C"` when appropriate
+4.6.8. Use `extern "C"` when appropriate
Explanation:
-------------------------------------------------------------------------------
-5.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
+4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
Explanation:
-------------------------------------------------------------------------------
-5.7. General Coding Practices
+4.7. General Coding Practices
-5.7.1. Turn on warnings
+4.7.1. Turn on warnings
Explanation
-------------------------------------------------------------------------------
-5.7.2. Provide a default case for all switch statements
+4.7.2. Provide a default case for all switch statements
Explanation:
-------------------------------------------------------------------------------
-5.7.3. Try to avoid falling through cases in a switch statement.
+4.7.3. Try to avoid falling through cases in a switch statement.
Explanation:
-------------------------------------------------------------------------------
-5.7.4. Use 'long' or 'short' Instead of 'int'
+4.7.4. Use 'long' or 'short' Instead of 'int'
Explanation:
-------------------------------------------------------------------------------
-5.7.5. Don't mix size_t and other types
+4.7.5. Don't mix size_t and other types
Explanation:
-------------------------------------------------------------------------------
-5.7.6. Declare each variable and struct on its own line.
+4.7.6. Declare each variable and struct on its own line.
Explanation:
-------------------------------------------------------------------------------
-5.7.7. Use malloc/zalloc sparingly
+4.7.7. Use malloc/zalloc sparingly
Explanation:
-------------------------------------------------------------------------------
-5.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
+4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
Explanation:
-------------------------------------------------------------------------------
-5.7.9. Add loaders to the `file_list' structure and in order
+4.7.9. Add loaders to the `file_list' structure and in order
Explanation:
-------------------------------------------------------------------------------
-5.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
+4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
Explanation:
-------------------------------------------------------------------------------
-5.8. Addendum: Template for files and function comment blocks:
+4.8. Addendum: Template for files and function comment blocks:
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.42 2002/05/05 20:26:02 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.42 2002/05/05 20:26:02 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
-------------------------------------------------------------------------------
-6. Version Control Guidelines
-
-To be filled. note on cvs comments. Don't only comment what you did, but also
-why you did it!
-
--------------------------------------------------------------------------------
-
-7. Testing Guidelines
+5. Testing Guidelines
To be filled.
-------------------------------------------------------------------------------
-7.1. Testplan for releases
+5.1. Testplan for releases
Explain release numbers. major, minor. developer releases. etc.
-------------------------------------------------------------------------------
-7.2. Test reports
+5.2. Test reports
Please submit test reports only with the test form at sourceforge. Three simple
steps:
-------------------------------------------------------------------------------
-8. Releasing a new version
+6. Releasing a New Version
+
+When we release versions of Privoxy, 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.
-To minimize trouble with distribution contents, web-page 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.
+So when releasing a new version, please adhere exactly to the procedure
+outlined in this chapter.
The following programs are required to follow this process: ncftpput (ncftp),
-scp (ssh), gmake (GNU's version of make), autoconf, cvs, ???.
+scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
-Replace X, Y and Z with the actual version number (X = major, Y = minor, Z =
-point):
+-------------------------------------------------------------------------------
+
+6.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
+6.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 in configure.in in CVS. Also, increase or
- reset the RPM release number in configure.in as appropriate. Do NOT touch
- version information after export from CVS. All packages will use the
- version and release data from configure.in. 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 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}
-
Then change the version info in doc/webserver/actions/index.php, line:
'$required_actions_file_version = "A.B";'
+ * 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.
+
* 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.
- * The first package uploaded should be the official "tarball" release, as
- required by the GPL. This is built with the "make tarball-dist" Makefile
- target, and then can be uploaded with "make tarball-upload" (see below).
+ * 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. Update the webserver
+6.3. Building and Releasing the Packages
-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
-doc/webserver/* directory (or create new directories under doc/webserver), then
-do
+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.
- make webserver
-
+For all types of packages, including the source tarball, you must make sure
+that you build from clean sources by exporting the right version from CVS into
+an empty directory:.
+
+ mkdir dist # delete or choose different name if it already exists
+ cd dist
+ 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
-This will do the upload to the webserver (www.privoxy.org).
+Do NOT change 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.
-Note that "make dok" (or "make redhat-dok") creates doc/webserver/user-manual,
-doc/webserver/developer-manual, doc/webserver/faq and doc/webserver/index.html
-automatically. (doc/webserver/man-page/privoxy-man-page.html is created by a
-separate Makefile target, "make man", due to dependencies on some obscure perl
-scripts. See comments in GNUmakefile.)
+Please find additional instructions for the source tarball and the individual
+platform dependent binary packages below.
-Someone should also commit these to CVS so that packagers without the ability
-to build docs locally, have access to them. This is a separate step, and should
-also be done before each official release.
+-------------------------------------------------------------------------------
+
+6.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:
-Please do NOT use any other means of transferring files to the webserver. "make
-webserver" not only uploads, but will make sure that the appropriate
-permissions are preserved for shared group access.
+ cd current
+ autoheader && autoconf && ./configure
+
+Then do:
+
+ make tarball-dist
+
+To upload the package to Sourceforge, simply issue
+
+ make tarball-upload
+
+Go to the displayed URL and release the file publicly on Sourceforge. For the
+change log field, use the relevant section of the ChangeLog file.
-------------------------------------------------------------------------------
-8.3. SuSE or Red Hat
+6.3.2. SuSE or Red Hat RPM
+
+In following text, replace dist with either "rh" for Red Hat or "suse" for
+SuSE.
-Ensure that you have the latest code version. Hence run:
+First, make sure that you have freshly exported the right version into an empty
+directory. (See "Building and releasing packages" above).
- 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 current
-
+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.
-first.
+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.
+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.4. OS/2
+6.3.3. OS/2
-Ensure that you have the latest code version. Hence run:
+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
+Setup module:
- 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
-
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
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
the final executable filename. For example,
installExeName='privoxyos2_setup_X.Y.Z.exe'
-
Next, edit the IJB.wis file so the release number matches in the PACKAGEID
section:
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
-
You're now ready to build. Run:
os2build
-
-And in the ./files directory you will have the WarpIN-installable executable.
+You will find the WarpIN-installable executable in the ./files directory.
Upload this anonymously to uploads.sourceforge.net/incoming, create a release
-for it, and you're done.
+for it, and you're done. Use the release notes and Change Log from the source
+tarball package.
-------------------------------------------------------------------------------
-8.5. Solaris
+6.3.4. Solaris
-Login to Sourceforge's compilefarm via ssh
+Login to Sourceforge's compilefarm via ssh:
ssh cf.sourceforge.net
-
-Choose the right operating system (not the Debian one). If you have downloaded
-Privoxy before,
-
- 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 current
-
-
-If not, please checkout Privoxy via CVS first. Run:
+Choose the right operating system (not the Debian one). When logged in, make
+sure that you have freshly exported the right version into an empty directory.
+(See "Building and releasing packages" above). Then run:
+ cd current
autoheader && autoconf && ./configure
-
Then run
gmake solaris-dist
-
which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
on the Sourceforge machine (no ncftpput). You now have to manually upload the
-archive to Sourceforge's ftp server and release the file publicly.
+archive to Sourceforge's ftp server and release the file publicly. Use the
+release notes and Change Log from the source tarball package.
-------------------------------------------------------------------------------
-8.6. Windows
+6.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.
-First check out a clean copy of the correct code version, by running:
-
- mkdir dist
- cd dist
- 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 .
-
+First, make sure that you have freshly exported the right version into an empty
+directory. (See "Building and releasing packages" above). Then get the Windows
+setup module:
-(Note: It is important that this is a clean copy of the code, do not re-use a
-working directory after you have manually compiled there).
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
Then you can build the package. This is fully automated, and is controlled by
winsetup/GNUmakefile. All you need to do is:
cd winsetup
make
-
Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and
-upload it to SourceForge.
+upload it to SourceForge. When releasing the package on SourceForge, use the
+release notes and Change Log from the source tarball package.
-------------------------------------------------------------------------------
-8.7. Debian
+6.3.6. Debian
-Ensure that you have the latest code version. Hence run:
-
- 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 current
-
-
-first. Run:
+First, make sure that you have freshly exported the right version into an empty
+directory. (See "Building and releasing packages" above). Then, run:
+ cd current
autoheader && autoconf && ./configure
-
Then do FIXME.
-------------------------------------------------------------------------------
-8.8. Mac OSX
+6.3.7. Mac OSX
-Ensure that you have the latest code version. Hence run:
+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
+setup module:
- 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
-
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
-From the osxsetup directory, run:
+Then run:
+ cd osxsetup
build
-
This will run autoheader, autoconf and configure as well as make. Finally, it
will copy over the necessary files to the ./osxsetup/files directory for
distributable zip file with the command:
zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
-
You can then upload privoxyosx_setup_x.y.z.zip anonymously to
-uploads.sourceforge.net/incoming, create a release for it, and you're done.
+uploads.sourceforge.net/incoming, create a release for it, and you're done. Use
+the release notes and Change Log from the source tarball package.
-------------------------------------------------------------------------------
-8.9. FreeBSD
-
-Change the version number of Privoxy in the configure.in file. Run:
-
- autoheader && autoconf && ./configure
-
-
-Then ...
+6.3.8. FreeBSD
Login to Sourceforge's compilefarm via ssh:
ssh cf.sourceforge.net
-
-
-Choose the right operating system.
-
- 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 current
-
-Run:
+Choose the right operating system. When logged in, make sure that you have
+freshly exported the right version into an empty directory. (See "Building and
+releasing packages" above). Then run:
+ cd current
autoheader && autoconf && ./configure
-
Then run:
gmake freebsd-dist
-
which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
on the Sourceforge machine (no ncftpput). You now have to manually upload the
-archive to Sourceforge's ftp server and release the file publicly.
+archive to Sourceforge's ftp server and release the file publicly. Use the
+release notes and Change Log from the source tarball package.
-------------------------------------------------------------------------------
-8.10. Tarball
-
-Ensure that you have the right code version. Hence run:
+6.3.9. HP-UX 11
- 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 current
-
-
-first. Run:
+First, make sure that you have freshly exported the right version into an empty
+directory. (See "Building and releasing packages" above). Then run:
+ cd current
autoheader && autoconf && ./configure
-
-Then do:
+Then do FIXME.
- make tarball-dist
-
+-------------------------------------------------------------------------------
-To upload the package to Sourceforge, simply issue
+6.3.10. Amiga OS
- make tarball-upload
-
+First, make sure that you have freshly exported the right version into an empty
+directory. (See "Building and releasing packages" above). Then run:
-Goto the displayed URL and release the file publicly on Sourceforge.
+ cd current
+ autoheader && autoconf && ./configure
+
+Then do FIXME.
-------------------------------------------------------------------------------
-8.11. HP-UX 11
+6.3.11. AIX
-Ensure that you have the latest code version. Hence run:
+Login to Sourceforge's compilefarm via ssh:
- 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 current
-
+ ssh cf.sourceforge.net
-first. Run:
+Choose the right operating system. When logged in, make sure that you have
+freshly exported the right version into an empty directory. (See "Building and
+releasing packages" above). Then run:
+ cd current
autoheader && autoconf && ./configure
-
-Then do FIXME.
+Then run:
+
+ make aix-dist
+
+which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload 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.
-------------------------------------------------------------------------------
-8.12. Amiga OS
+6.4. Uploading and Releasing Your Package
-Ensure that you have the latest code version. Hence run:
+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:
- 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 current
-
+ * Upload to: ftp://upload.sourceforge.net/incoming
+
+ * user: anonymous
+
+ * 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 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.15 (beta).
-first. Run:
+Now just follow the prompts. Be sure to add any appropriate Release notes. You
+should see your freshly uploaded packages in "Step 2. Add Files To This
+Release". Check the appropriate box(es). Remember at each step to hit the
+"Refresh/Submit" 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 "Update" for each file. If anyone is monitoring your platform,
+check the "email" box at the very bottom to notify them of the new package.
+This should do it!
- autoheader && autoconf && ./configure
-
+If you have made errors, or need to make changes, you can go through
+essentially the same steps, but select Edit Release, instead of Add Release.
-Then do FIXME.
+-------------------------------------------------------------------------------
+
+6.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
+download". Be sure to include the download location, the release notes and the
+change log.
-------------------------------------------------------------------------------
-8.13. AIX
+7. Update the Webserver
-Login to Sourceforge's compilefarm via ssh:
+When updating the webserver, please follow these steps to make sure that no
+broken links, incosistent contents or permission problems will occur:
- ssh cf.sourceforge.net
-
+If you have changed anything in the documentation source SGML files, do:
-Choose the right operating system. If you have downloaded Privoxy before:
+ make dok # (or make redkat-dok if make dok doesn't work for you)
- 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 current
-
+That will generate doc/webserver/user-manual, doc/webserver/developer-manual,
+doc/webserver/faq and doc/webserver/index.html automatically.
-If not, please checkout Privoxy via CVS first. Run:
+If you changed the manual page source, generate doc/webserver/man-page/
+privoxy-man-page.html by running "make man". (This is a separate target due to
+dependencies on some obscure perl scripts. See comments in GNUmakefile.)
- autoheader && autoconf && ./configure
-
+If you want to add new files to the webserver, create them locally in the doc/
+webserver/* directory (or create new directories under doc/webserver).
-Then run:
+Next, commit any changes from the above steps to CVS. All set? Then do
- make aix-dist
-
+ make webserver
-which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
-the Sourceforge machine (no ncftpput). You now have to manually upload the
-archive to Sourceforge's ftp server and release the file publicly.
+This will do the upload to the webserver (www.privoxy.org) and ensure all files
+and directories there are group writable.
+
+Please do NOT use any other means of transferring files to the webserver to
+avoid permission problems.
-------------------------------------------------------------------------------
-9. Contacting the developers, Bug Reporting and Feature Requests
+8. Contacting the developers, Bug Reporting and Feature Requests
We value your feedback. However, to provide you with the best support, please
-note:
+note the following sections.
+
+-------------------------------------------------------------------------------
+
+8.1. Get Support
+
+To get support, use the Sourceforge Support Forum:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=211118
- * Use the Sourceforge Support Forum to get help:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=211118
-
-
- * Submit bugs only through our Sourceforge Bug Forum:
-
- http://sourceforge.net/tracker/?group_id=11118&atid=111118.
-
-
- Make sure that the bug has not already been submitted. Please try to verify
- that it is a Privoxy bug, and not a browser or site bug first. If you are
- using your own custom configuration, please try the stock configs to see if
- the problem is a configuration related bug. And if not using the latest
- development snapshot, please try the latest one. Or even better, CVS
- sources. Please be sure to include the Privoxy/Junkbuster version,
- platform, browser, any pertinent log data, any other relevant details
- (please be specific) and, if possible, some way to reproduce the bug.
-
- * Submit feature requests only through our Sourceforge feature request forum:
-
- http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
-
-
- * You can also send feedback on websites that Privoxy has problems with. Please bookmark
- the following link: "Privoxy - Submit Filter Feedback"
- . Once you surf to a page with problems, use the
- bookmark to send us feedback. We will look into the issue as soon as possible.
-
-
- * For any other issues, feel free to use the mailing lists:
-
- http://sourceforge.net/mail/?group_id=11118.
-
-
- Anyone interested in actively participating in development and related
- discussions can also join the appropriate mailing list. Archives are
- available, too.
-
-------------------------------------------------------------------------------
-10. Copyright and History
+8.2. Report bugs
+
+To submit bugs, use the Sourceforge Bug Forum:
+
+ http://sourceforge.net/tracker/?group_id=11118&atid=111118.
+
+Make sure that the bug has not already been submitted. Please try to verify
+that it is a Privoxy bug, and not a browser or site bug first. If you are using
+your own custom configuration, please try the stock configs to see if the
+problem is a configuration related bug. And if not using the latest development
+snapshot, please try the latest one. Or even better, CVS sources. Please be
+sure to include the Privoxy version, platform, browser, any pertinent log data,
+any other relevant details (please be specific) and, if possible, some way to
+reproduce the bug.
+
+-------------------------------------------------------------------------------
-10.1. Copyright
+8.3. Request new features
+
+To submit ideas on new features, use the Sourceforge feature request forum:
+
+ http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
+
+-------------------------------------------------------------------------------
+
+8.4. Report ads or other filter problems
+
+You can also send feedback on websites that Privoxy has problems with. Please
+bookmark the following link: "Privoxy - Submit Filter Feedback". Once you surf
+to a page with problems, use the bookmark to send us feedback. We will look
+into the issue as soon as possible.
+
+New, improved default.action files will occasionally be made available based on
+your feedback. These will be announced on the ijbswa-announce list.
+
+-------------------------------------------------------------------------------
+
+8.5. Other
+
+For any other issues, feel free to use the mailing lists:
+
+ http://sourceforge.net/mail/?group_id=11118.
+
+Anyone interested in actively participating in development and related
+discussions can also join the appropriate mailing list. Archives are available,
+too. See the page on Sourceforge.
+
+-------------------------------------------------------------------------------
+
+9. Privoxy Copyright, License and History
+
+Copyright © 2001, 2002 by Privoxy Developers <developers@privoxy.org>
+
+Some source code is based on code Copyright © 1997 by Anonymous Coders and
+Junkbusters, Inc. and licensed under the GNU General Public License.
+
+-------------------------------------------------------------------------------
+
+9.1. License
Privoxy 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 your option) any later
-version.
+terms of the GNU General Public License, version 2, as published by the Free
+Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
330, Boston, MA 02111-1307, USA.
You should have received a copy of the GNU General Public License along with
-this program; if not, write to the Free Software Foundation, Inc., 59 Temple
-Place, Suite 330, Boston, MA 02111-1307 USA.
+this program; if not, write to the
+
+ Free Software
+ Foundation, Inc. 59 Temple Place - Suite 330
+ Boston, MA 02111-1307
+ USA
-------------------------------------------------------------------------------
-10.2. History
+9.2. History
Privoxy is evolved, and derived from, the Internet Junkbuster, with many
improvments and enhancements over the original.
-------------------------------------------------------------------------------
-11. See also
+10. See also
Other references and sites of interest to Privoxy users:
http://p.p/, access Privoxy from your browser. Alternately, http://
config.privoxy.org may work in some situations where the first does not.
-http://p.p/, and select "actions file feedback system" to submit "misses" to
-the developers.
+http://p.p/, and select "Privoxy - Submit Filter Feedback" to submit "misses"
+to the developers.
http://www.junkbusters.com/ht/en/cookies.html
projects / privoxy.git / blobdiff