X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=01fe1da3928985f876cce1a16b2c646b7ba8d1ca;hp=2c3fb12df271b259693640c454c40bf1513c12f6;hb=9d463432b4e7421b58ea6b6762dbb427e83d9780;hpb=0c0171d3f0339ee3075ae384a58613ca88334460 diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 2c3fb12d..01fe1da3 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -1,4 +1,21 @@ - + + + + + + + + + + + + + + + + +]>
- Junkbuster Developer Manual + Privoxy Developer Manual + + + + + Copyright &my-copy; 2001, 2002 by + Privoxy Developers + + - $Id: developer-manual.sgml,v 1.6 2002/02/24 14:25:06 jongfoster Exp $ - - - - By: Junkbuster Developers - - - + $Id: developer-manual.sgml,v 1.46 2002/05/22 17:15:00 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. Internet Junkbuster 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. Junkbuster has a very flexible -configuration and can be customized to suit individual needs and -tastes. Internet Junkbuster has application for -both stand-alone systems and multi-user networks. + + + + + + + This is here to keep vim syntax file from breaking :/ + If I knew enough to fix it, I would. + PLEASE DO NOT REMOVE! HB: hal@foobox.net + + ]]> + + The developer manual provides guidance on coding, testing, packaging, documentation + and other issues of importance to those involved with + Privoxy development. It is mandatory (and helpful!) reading + for anyone who wants to join the team. + + + + + + + + + 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. + @@ -55,41 +107,497 @@ Please see the Contact section in the user-manual if you want to contact the dev - + + Introduction - To be filled. - - + + + Privoxy, as an heir to + Junkbuster, is an Open Source project + and licensed under the GPL. As such, Privoxy + development is potentially open to anyone who has the time, knowledge, + and desire to contribute in any capacity. Our goals are simply to + continue the mission, to improve Privoxy, and + to make it available to as wide an audience as possible. + + + One does not have to be a programmer to contribute. Packaging, testing, + and porting, are all important jobs as well. + - Quickstart to Junkbuster Development - To be filled. - + 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 + refer to the extensive comments in the source code. + + - Documentation Guidelines + The CVS Repository - All docs are in SGML format and located in the doc/source directory. - - - How do you update the webserver (i.e. the pages on sourceforge)? + 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. + + + 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. + + + + 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). + + + + + + Discussing Changes First + + We don't have a too formal policy on this, just use common sense. Hints: If it is.. - - Run make dok (which uses the documents in doc/source to update all - text files in doc/text and to update -all web documents in doc/webserver. - - - Run make webserver which copies all files from -doc/webserver to the sourceforge webserver -via scp. - + + ..a bugfix / clean-up / cosmetic thing: shoot + + + ..a new feature that can be turned off: shoot + + + ..a clear improvement w/o side effects on other parts of the code: shoot + + + ..a matter of taste: ask the list + + + ..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. There is always the possibility + to submit a patch to the patches + tracker instead. + + + + + +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 modular stylesheets (or comparable alternatives), + and either jade or + openjade (recommended) installed in order to + build docs from source. Currently there is user-manual, + FAQ, and, of + course this, the developer-manual in this format. + The README, AUTHORS + privoxy.1 (man page) files are also now maintained + as Docbook SGML. The finished files are all in the top-level source + directory are generated files! Also, index.html, the + Privoxy home page, is maintained as SGML. + DO NOT edit these directly. Edit the SGML source, or + contact someone involved in the documentation (at present Stefan and + Hal). + + + Other, less formal documents (e.g. LICENSE, + INSTALL) are maintained as plain text files in the + top-level source directory. At least for the time being. + + + Packagers are encouraged to include this documentation. For those without + the ability to build the docs locally, text versions of each are kept in + CVS. HTML versions are also now being kept in CVS under + doc/webserver/*. + + + Formal documents are built with the Makefile targets of + make dok, or alternately + make redhat-dok. If you have problems, + try both. The build process uses the document SGML sources in + doc/source/*/* to update all text files in + doc/text/ and to update all HTML + documents in doc/webserver/. + + + Documentation writers should please make sure documents build + successfully before committing to CVS, if possible. + + + How do you update the webserver (i.e. the pages on privoxy.org)? + + + + First, build the docs by running make + dok (or alternately make + redhat-dok). + + + Run make webserver which copies all + files from doc/webserver to the + sourceforge webserver via scp. + + + + + Finished docs should be occasionally submitted to CVS + (doc/webserver/*/*.html) so that those without + the ability to build them locally, have access to them if needed. + This is especially important just prior to a new release! Please + do this after the $VERSION and + other release specific data in configure.in has been + updated (this is done just prior to a new release). + + + + +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 languages. In fact, HTML is an SGML application. Both will use + tags to format text and other content. SGML tags can be much + more varied, and flexible, but do much of the same kinds of things. The tags, + or elements, are definable in SGML. There is no set + standards. Since we are using + Docbook, our tags are those that are defined by + Docbook. Much of how the finish document is + rendered is determined by the stylesheets. + The stylesheets determine how each tag gets translated to HTML, or other + formats. + + + + Tags in Docbook SGML need to be always closed. If not, you + will likely generate errors. Example: <title>My + Title</title>. They are also case-insensitive, but we + strongly suggest using all lower case. This keeps compatibility with + [Docbook] XML. + + + + Our documents use sections for the most part. Sections + will be processed into HTML headers (e.g. h1 for + sect1). The Docbook stylesheets + will use these to also generate the Table of Contents for each doc. Our + TOC's are set to a depth of three. Meaning sect1, + sect2, and sect3 will have TOC + entries, but sect4 will not. Each section requires + a <title> element, and at least one + <para>. There is a limit of five section + levels in Docbook, but generally three should be sufficient for our + purposes. + + + + 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. + + + + + + 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. + + + + + + <application>Privoxy</application> 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 fashion. + + + Here it is: + + + + + + All tags should be lower case. + + + + + Tags delimiting a block of text (even small + blocks) should be on their own line. Like: + + <para> + Some text goes here. + </para> + + Tags marking individual words, or few words, should be in-line: + + Just to <emphasis>emphasize</emphasis>, some text goes here. + + + + + + Tags should be nested and step indented for block text like: (except + in-line tags) + + <para> + <itemizedlist> + <para> + <listitem> + Some text goes here in our list example. + </listitem> + </para> + </itemizedlist> + </para> + + This makes it easier to find the text amongst the tags ;-) + + + + + Use white space to separate logical divisions within a document, + like between sections. Running everything together consistently + makes it harder to read and work on. + + + + + Do not hesitate to make comments. Comments can either use the + <comment> element, or the <!-- --> style comment + familiar from HTML. (Note in Docbook v4.x <comment> is + replaced by <remark>.) + + + + + We have an international audience. Refrain from slang, or English + idiosyncrasies (too many to list :). Humor also does not translate + well sometimes. + + + + + Try to keep overall line lengths in source files to 80 characters or less + for obvious reasons. This is not always possible, with lengthy URLs for + instance. + + + + + Our documents are available in differing formats. Right now, they + are just plain text, and HTML, but PDF, and others is always a + future possibility. Be careful with URLs (<ulink>), and avoid + this mistake: + + + My favorite site is <ulink url="http://example.com">here</ulink>. + + + This will render as My favorite site is here, which is + not real helpful in a text doc. Better like this: + + + My favorite site is <ulink url="http://example.com">example.com</ulink>. + + + + + All documents should be spell checked occasionally. + aspell can check SGML with the + -H option. (ispell I think + too.) + + + + + + + + + + + + Privoxy Custom Entities + + Privoxy documentation is using + a number of customized entities to facilitate + documentation maintenance. + + + We are using a set of boilerplate files with generic text, + that is used by multiple docs. This way we can write something once, and use + it repeatedly without having to re-write the same content over and over again. + If editing such a file, keep in mind that it should be + generic. That is the purpose; so it can be used in varying + contexts without additional modifications. + + + We are also using what Docbook calls + internal entities. These are like variables in + programming. Well, sort of. For instance, we have the + p-version entity that contains the current + Privoxy version string. You are strongly + encouraged to use these where possible. Some of these obviously + require re-setting with each release (done by the Makefile). A sampling of + custom entities are listed below. See any of the main docs for examples. + + + + + + + Re- boilerplate text entities are defined like: + + + <!entity supported SYSTEM "supported.sgml"> + + + In this example, the contents of the file, + supported.sgml is available for inclusion anywhere + in the doc. To make this happen, just reference the now defined + entity: &supported; (starts with an ampersand + and ends with a semi-colon), and the contents will be dumped into + the finished doc at that point. + + + + + Commonly used internal entities: + + + + p-version: the Privoxy + version string, e.g. &p-version;. + + + 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). + + + p-stable: just the opposite. + + + p-text: this doc is only generated as text. + + + + + + + There are others in various places that are defined for a specific + purpose. Read the source! + + + + - + @@ -97,16 +605,16 @@ via scp. 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 Junkbusters" consistent and reliable. Thus - making maintenance easier and increasing chances of success of - the project. + 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" consistent and reliable. Thus making + maintenance easier and increasing chances of success of the + project. - And that of course comes back to us as individuals. If we - can increase our development and product efficiencies then we - can solve more of the request for changes/improvements and in - general feel good about ourselves. ;-> + And that of course comes back to us as individuals. If we can + increase our development and product efficiencies then we can solve more + of the request for changes/improvements and in general feel good about + ourselves. ;-> @@ -188,7 +696,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ Exception: If you are trying to add a small logic comment and do not - wish to "disrubt" the flow of the code, feel free to use a 1 + wish to "disrupt" the flow of the code, feel free to use a 1 line comment which is NOT on the same line as the code. @@ -334,12 +842,12 @@ if ( 1 == X ) Explanation: - Use all lowercase, and seperate words via an underscore + Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever - decide to port JunkBuster to C++. + decide to port Privoxy to C++. Example: @@ -361,12 +869,12 @@ int msiis5hack = 0; int msIis5Hack = 0; Explanation: - Use all lowercase, and seperate words via an underscore + Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever - decide to port JunkBuster to C++. + decide to port Privoxy to C++. Example: @@ -503,11 +1011,11 @@ if ( this == that ) Note: In the special case that the if-statement is inside a loop, and it is trivial, i.e. it tests for a - condidtion that is obvious from the purpose of the block, + condition that is obvious from the purpose of the block, one-liners as above may optically preserve the loop structure and make it easier to read. - Status: developer-discrection. + Status: developer-discretion. Example exception: @@ -569,7 +1077,7 @@ structure->flag = ( condition ); if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } - Note: The former is readable and consice. The later + Note: The former is readable and concise. The later is wordy and inefficient. Please assume that any developer new to the project has at least a "good" knowledge of C/C++. (Hope I do not offend by that last comment ... 8-) @@ -650,14 +1158,14 @@ int function2( ... ) function2( ... ) { } Note: Use 1 blank line before the closing brace and 2 - lines afterwards. This makes the end of function standout to + lines afterward. This makes the end of function standout to the most casual viewer. Although function comments help - seperate functions, this is still a good coding practice. In + separate functions, this is still a good coding practice. In fact, I follow these rules when using blocks in "for", "while", "do" loops, and long if {} statements too. After all whitespace is free! - Status: developer-discrection on the number of blank + Status: developer-discretion on the number of blank lines. Enforced is the end of function comments. @@ -725,7 +1233,7 @@ struct *ptr = NULL; and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. arrayPtr[0]. - Status: developer-discrection if and only if the + Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. @@ -824,7 +1332,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) char *s2 ); I could then not use it to compare argv's in main: int main( - int argc, const char *argv[] ) { strcmp( argv[0], "junkbusters" + int argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); } Both these pointers are *const*! If the c runtime library @@ -878,7 +1386,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include - "file.h" behaviour. + "file.h" behavior. @@ -951,9 +1459,9 @@ extern file_list *xyz; Note: If you declare "file_list xyz;" (without the pointer), then including the proper header file is necessary. If you only want to prototype a pointer, however, the header - file is unneccessary. + file is unnecessary. - Status: Use with discrection. + Status: Use with discretion. @@ -999,7 +1507,7 @@ switch( hash_string( cmd ) ) default : log_error( ... ); - ... anomly code goes here ... + ... anomaly code goes here ... continue; / break; / exit( 1 ); / etc ... } /* end switch( hash_string( cmd ) ) */ @@ -1010,7 +1518,7 @@ switch( hash_string( cmd ) ) This API call *should* be included in a default statement. Another Note: This is not so much a readability issue - as a robust programming issue. The "anomly code goes here" may + as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream (as in load_config). Or it may really be an ABEND condition. @@ -1107,7 +1615,7 @@ long c = 0; on 1 line. You should, although, provide a good comment on their functions. - Status: developer-discrection. + Status: developer-discretion. @@ -1117,7 +1625,7 @@ long c = 0; Explanation: - Create a local stuct (on the stack) if the variable will + Create a local struct (on the stack) if the variable will live and die within the context of one function call. Only "malloc" a struct (on the heap) if the variable's life @@ -1126,7 +1634,7 @@ long c = 0; Example: If a function creates a struct and stores a pointer to it in a -list, then it should definately be allocated via `malloc'. +list, then it should definitely be allocated via `malloc'. @@ -1142,7 +1650,7 @@ list, then it should definately be allocated via `malloc'. responsible for ensuring that deletion is timely (i.e. not too soon, not too late). This is known as "low-coupling" and is a "good thing (tm)". You may need to offer a - free/unload/destuctor type function to accomodate this. + free/unload/destuctor type function to accommodate this. Example: @@ -1155,7 +1663,7 @@ static void unload_re_filterfile( void *f ) { ... } functions for C run-time library functions ... such as `strdup'. - Status: developer-discrection. The "main" use of this + Status: developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested). @@ -1182,16 +1690,16 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to - exitinst code, use FIXME + existing code, use FIXME Explanation: If you have enough confidence in new code or confidence in - your changes, but are not *quite* sure of the reprocussions, + your changes, but are not *quite* sure of the repercussions, add this: /* FIXME: this code has a logic error on platform XYZ, * - attempthing to fix */ #ifdef PLATFORM ...changed code here... + attempting to fix */ #ifdef PLATFORM ...changed code here... #endif or: @@ -1206,7 +1714,7 @@ static void unload_re_filterfile( void *f ) { ... } Note: If you make it clear that this may or may not be a "good thing (tm)", it will be easier to identify and - include in the project (or conversly exclude from the + include in the project (or conversely exclude from the project). @@ -1219,7 +1727,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.6 2002/02/24 14:25:06 jongfoster Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46 2002/05/22 17:15:00 oes Exp $"; /********************************************************************* * * File : $Source$ @@ -1227,7 +1735,7 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.6 2002/02/24 14:25:0 * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001 the SourceForge - * IJBSWA team. http://ijbswa.sourceforge.net + * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written * by and Copyright (C) 1997 Anonymous Coders and @@ -1271,7 +1779,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; Note: The formfeed character that is present right after the comment flower box is handy for (X|GNU)Emacs users to - skip the verbige and get to the heart of the code (via + skip the verbiage and get to the heart of the code (via `forward-page' and `backward-page'). Please include it if you can. @@ -1279,7 +1787,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.6 2002/02/24 14:25:06 jongfoster Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46 2002/05/22 17:15:00 oes Exp $" /********************************************************************* * * File : $Source$ @@ -1287,7 +1795,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001 the SourceForge - * IJBSWA team. http://ijbswa.sourceforge.net + * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written * by and Copyright (C) 1997 Anonymous Coders and @@ -1375,13 +1883,6 @@ int FUNCTION_NAME( void *param1, const char *x ) - - Version Control Guidelines - To be filled. note on cvs comments. don't comment what you did, comment -why you did it. - - - Testing Guidelines To be filled. @@ -1390,7 +1891,7 @@ why you did it. Testplan for releases -Explain release numbers. major, minor. developer releases. etc. + Explain release numbers. major, minor. developer releases. etc. @@ -1399,20 +1900,20 @@ Remove any existing rpm with rpm -e Remove any file that was left over. This includes (but is not limited to) - /var/log/junkbuster - /etc/junkbuster - /usr/sbin/junkbuster - /etc/init.d/junkbuster - /usr/doc/junkbuster* + /var/log/privoxy + /etc/privoxy + /usr/sbin/privoxy + /etc/init.d/privoxy + /usr/doc/privoxy* Install the rpm. Any error messages? - start,stop,status junkbuster with the specific script - (e.g. /etc/rc.d/init/junkbuster stop). Reboot your machine. Does + start,stop,status Privoxy with the specific script + (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart work? - Start browsing. Does the junkbuster work? Logfile written? + Start browsing. Does Privoxy work? Logfile written? Remove the rpm. Any error messages? All files removed? @@ -1426,7 +1927,7 @@ at sourceforge. Three simple steps: Select category: the distribution you test on. - Select group: the version of Junkbuster that we are about to release. + Select group: the version of Privoxy that we are about to release. Fill the Summary and Detailed Description with something intelligent (keep it short and precise). @@ -1436,23 +1937,860 @@ at sourceforge. Three simple steps: - + - Contact the developers - Please see the user manual for information on how to contact the developers. + 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. + + + 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 (ssh), + gmake (GNU's version of make), autoconf, cvs. + + + + 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. + + + + + + + + + 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. Announce the + freeze so that nobody will interfere with last minute changes. + + + + + Increment the version number (point from odd to even in development + branches!) in configure.in. + + + + + 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. + + + + + 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). + + + + + + + + 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. + + + + 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 + + + + + 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. + + + + 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. + + + Note on Privoxy Packaging + + Please keep these general guidelines in mind when putting together + your package. These apply to all platforms! + + + + + + Privoxy requires + write access to: all *.action files, all + logfiles, and the trust file. You will + need to determine the best way to do this for your platform. + + + + + Please include up to date documentation. At a bare minimum: + + + + LICENSE (toplevel directory) + + + + + README (toplevel directory) + + + + + AUTHORS (toplevel directory) + + + + + man page (toplevel directory, Unix-like + platforms only) + + + + + The User Manual (doc/webserver/user-manual/) + + + + + FAQ (doc/webserver/faq/) + + + + Also suggested: Developer Manual + (doc/webserver/devel-manual) and ChangeLog + (toplevel directory). FAQ and the manuals are + HTML docs. There are also text versions in + doc/text/ which could conceivably also be + included. + + + The documentation has been designed such that the manuals are linked + to each other from parallel directories, and should be packaged + that way. index.html can also be included and + can serve as a focal point for docs and other links of interest. + This should be one level up from the manuals. There are two + css stylesheets that can be included for better presentation: + p_doc.css and p_web.css. + These should be in the same directory with + index.html, (i.e. one level up from the manual + directories). + + + + + user.action is designed for local preferences. + Make sure this does not get overwritten! + + + + + Other configuration files should be installed as the new defaults, + but all previously installed configuration files should be preserved + as backups. This is just good manners :-) + + + + + Please check platform specific notes in this doc, if you haven't + done Privoxy 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). + + + + + + + + + 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: + + + + 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. + + + + SuSE, Conectiva 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). + + + 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 dist-dist + + + + To upload the package to Sourceforge, simply issue + + + + make dist-upload rpm_packagerev + + + + 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. + + + + 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 Setup module: + + + + 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 from + various sources like hobbes.nmsu.edu. + Specificially, you will need autoheader, + autoconf and sh tools. + The packaging takes place with WarpIN, available from various sources, including + its home page: xworkplace. + + + Change directory to the os2setup directory. + Edit the os2build.cmd file to set 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 + + + + 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. Use the release notes and Change Log from the + source tarball package. + + + + Solaris + + Login to Sourceforge's compilefarm via ssh: + + + + ssh cf.sourceforge.net + + + + 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. Use the release notes and Change Log from the + source tarball package. + + + + 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, 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: + + + + 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. When releasing the package on SourceForge, use the release notes + and Change Log from the source tarball package. + + + + Debian + + 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, run: + + + + make debian-dist + + + + To upload the package to Sourceforge, simply issue + + + + make debian-upload + + + + + 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 setup module: + + + + cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup + + + + 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 further processing by PackageMaker. + + + Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package + name to match the release, and hit the "Create package" button. + If you specify ./Privoxy.pkg as the output package name, you can then create + the 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. Use the release notes + and Change Log from the source tarball package. + + + + FreeBSD + + Login to Sourceforge's compilefarm via ssh: + + + + ssh cf.sourceforge.net + + + + 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. Use the release notes and Change Log from the + source tarball package. + + + + 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: + + + + cd current + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + 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: + + + + cd current + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + AIX + + Login to Sourceforge's compilefarm via ssh: + + + + ssh cf.sourceforge.net + + + + 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: + + + + 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. + + + + + + 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: + + + + + + Upload to: ftp://upload.sourceforge.net/incoming + + + + + user: anonymous + + + + + password: ijbswa-developers@lists.sourceforge.net + + + + + + Or use the make targets as described above. + + + 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. &p-version; + (beta). + + + 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! + + + 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. + + + + + 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. + + + - Copyright and History - Please see the user manual for information on Copyright and History. - + Update the Webserver + + When updating the webserver, please follow these steps to make + sure that no broken links, incosistent contents or permission + problems will occur: + + + If you have changed anything in the documentation source SGML files, + do: + + + + make dok # (or make redkat-dok if make dok doesn't work for you) + + + + That will generate doc/webserver/user-manual, + doc/webserver/developer-manual, + doc/webserver/faq and + doc/webserver/index.html automatically. + + + 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.) + + + 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). + + + Next, commit any changes from the above steps to CVS. All set? Then do + + + + make webserver + + + + 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. + + + + + Contacting the developers, Bug Reporting and Feature Requests + + &contacting; + + + +Privoxy Copyright, License and History + + + ©right; + + + +License + + &license; + + + + + +History + + &history; + + + + + See also - Please see the user manual for information on references. - + + &seealso; + +