X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Ftext%2Fdeveloper-manual.txt;h=ca4f08d00d0af7a1c16bdf1e3f81aed900ae9afa;hp=6b151678994a61450012f3c7dfa51fe1b982757a;hb=9c79b235e69182b1e8e1243d9da7918ccfc43ae6;hpb=07fa75519ff7a4eab719248dee98046fe0e8266f diff --git a/doc/text/developer-manual.txt b/doc/text/developer-manual.txt index 6b151678..ca4f08d0 100644 --- a/doc/text/developer-manual.txt +++ b/doc/text/developer-manual.txt @@ -1,8 +1,8 @@ Privoxy Developer Manual -By: Privoxy Developers +Copyright © 2001, 2002 by Privoxy Developers -$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $ +$Id: developer-manual.sgml,v 1.41 2002/05/04 08:44:44 swa 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. @@ -14,127 +14,128 @@ developers. ------------------------------------------------------------------------------- Table of Contents - 1. Introduction -3. Quickstart to Privoxy Development -4. The CVS Repository - 4.1. Access to CVS - 4.2. CVS Commit Guideline - 4.3. Discussing Changes First + 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. Documentation Guidelines +3. Documentation Guidelines - 5.1. Quickstart to Docbook and SGML - 5.2. Privoxy Documentation Style - 5.3. Privoxy Custom Entities + 3.1. Quickstart to Docbook and SGML + 3.2. Privoxy Documentation Style + 3.3. Privoxy Custom Entities -6. Coding Guidelines +4. Coding Guidelines - 6.1. Introduction - 6.2. Using Comments + 4.1. Introduction + 4.2. Using Comments - 6.2.1. Comment, Comment, Comment - 6.2.2. Use blocks for comments - 6.2.3. Keep Comments on their own line - 6.2.4. Comment each logical step - 6.2.5. Comment All Functions Thoroughly - 6.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 - 6.3. Naming Conventions + 4.3. Naming Conventions - 6.3.1. Variable Names - 6.3.2. Function Names - 6.3.3. Header file prototypes - 6.3.4. Enumerations, and #defines - 6.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 - 6.4. Using Space + 4.4. Using Space - 6.4.1. Put braces on a line by themselves. - 6.4.2. ALL control statements should have a block - 6.4.3. Do not belabor/blow-up boolean expressions - 6.4.4. Use white space freely because it is free - 6.4.5. Don't use white space around structure operators - 6.4.6. Make the last brace of a function stand out - 6.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 - 6.5. Initializing + 4.5. Initializing - 6.5.1. Initialize all variables + 4.5.1. Initialize all variables - 6.6. Functions + 4.6. Functions - 6.6.1. Name functions that return a boolean as a question. - 6.6.2. Always specify a return type for a function. - 6.6.3. Minimize function calls when iterating by using variables - 6.6.4. Pass and Return by Const Reference - 6.6.5. Pass and Return by Value - 6.6.6. Names of include files - 6.6.7. Provide multiple inclusion protection - 6.6.8. Use `extern "C"` when appropriate - 6.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 - 6.7. General Coding Practices + 4.7. General Coding Practices - 6.7.1. Turn on warnings - 6.7.2. Provide a default case for all switch statements - 6.7.3. Try to avoid falling through cases in a switch statement. - 6.7.4. Use 'long' or 'short' Instead of 'int' - 6.7.5. Don't mix size_t and other types - 6.7.6. Declare each variable and struct on its own line. - 6.7.7. Use malloc/zalloc sparingly - 6.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' - 6.7.9. Add loaders to the `file_list' structure and in order - 6.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 - 6.8. Addendum: Template for files and function comment blocks: + 4.8. Addendum: Template for files and function comment blocks: -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. Building and Releasing the Packages + 6.1. Version numbers + 6.2. Before the Release: Freeze + 6.3. Building and Releasing the Packages - 8.2.1. Source Tarball - 8.2.2. SuSE or Red Hat - 8.2.3. OS/2 - 8.2.4. Solaris - 8.2.5. Windows - 8.2.6. Debian - 8.2.7. Mac OSX - 8.2.8. FreeBSD - 8.2.9. HP-UX 11 - 8.2.10. Amiga OS - 8.2.11. AIX + 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 - 8.3. Uploading and Releasing Your Package - 8.4. After the Release + 6.4. Uploading and Releasing Your Package + 6.5. After the Release -9. Update the Webserver -10. Contacting the developers, Bug Reporting and Feature Requests +7. Update the Webserver +8. Contacting the developers, Bug Reporting and Feature Requests - 10.1. Get Support - 10.2. Report bugs - 10.3. Request new features - 10.4. Report ads or other filter problems - 10.5. Other + 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. Copyright and History +9. Copyright, License and History - 11.1. Copyright - 11.2. History + 9.1. Copyright + 9.2. License + 9.3. History -12. See also - -------------------------------------------------------------------------------- +10. See also 1. Introduction @@ -149,7 +150,7 @@ porting, are all important jobs as well. ------------------------------------------------------------------------------- -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. @@ -159,7 +160,7 @@ the extensive comments in the source code. ------------------------------------------------------------------------------- -4. The CVS Repository +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 @@ -167,7 +168,7 @@ chapter completely before accessing via CVS. ------------------------------------------------------------------------------- -4.1. Access to 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 @@ -177,7 +178,7 @@ tree module is called current. ------------------------------------------------------------------------------- -4.2. CVS Commit Guideline +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 @@ -205,7 +206,7 @@ guidelines: ------------------------------------------------------------------------------- -4.3. Discussing Changes First +2.3. Discussing Changes First We don't have a too formal policy on this, just use common sense. Hints: If it is.. @@ -226,7 +227,7 @@ to the patches tracker instead. ------------------------------------------------------------------------------- -5. 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 @@ -269,7 +270,7 @@ been updated (this is done just prior to a new release). ------------------------------------------------------------------------------- -5.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 @@ -315,7 +316,7 @@ useful. ------------------------------------------------------------------------------- -5.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 @@ -386,7 +387,7 @@ Here it is: ------------------------------------------------------------------------------- -5.3. Privoxy Custom Entities +3.3. Privoxy Custom Entities Privoxy documentation is using a number of customized "entities" to facilitate documentation maintenance. @@ -416,7 +417,7 @@ entities are listed below. See any of the main docs for examples. * 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"). @@ -428,9 +429,9 @@ Read the source! ------------------------------------------------------------------------------- -6. Coding Guidelines +4. Coding Guidelines -6.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" @@ -443,9 +444,9 @@ changes/improvements and in general feel good about ourselves. ;-> ------------------------------------------------------------------------------- -6.2. Using Comments +4.2. Using Comments -6.2.1. Comment, Comment, Comment +4.2.1. Comment, Comment, Comment Explanation: @@ -480,7 +481,7 @@ is actually being done. ------------------------------------------------------------------------------- -6.2.2. Use blocks for comments +4.2.2. Use blocks for comments Explanation: @@ -520,7 +521,7 @@ line as the code. ------------------------------------------------------------------------------- -6.2.3. Keep Comments on their own line +4.2.3. Keep Comments on their own line Explanation: @@ -570,7 +571,7 @@ short DoSomethingVeryImportant( ------------------------------------------------------------------------------- -6.2.4. Comment each logical step +4.2.4. Comment each logical step Explanation: @@ -585,7 +586,7 @@ these are usually major logic containers. ------------------------------------------------------------------------------- -6.2.5. Comment All Functions Thoroughly +4.2.5. Comment All Functions Thoroughly Explanation: @@ -602,7 +603,7 @@ document. ------------------------------------------------------------------------------- -6.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: @@ -635,9 +636,9 @@ if ( 1 == X ) ------------------------------------------------------------------------------- -6.3. Naming Conventions +4.3. Naming Conventions -6.3.1. Variable Names +4.3.1. Variable Names Explanation: @@ -657,7 +658,7 @@ int msiis5hack = 0; int msIis5Hack = 0; ------------------------------------------------------------------------------- -6.3.2. Function Names +4.3.2. Function Names Explanation: @@ -678,7 +679,7 @@ int loadSomeFile( struct client_state *csp ) ------------------------------------------------------------------------------- -6.3.3. Header file prototypes +4.3.3. Header file prototypes Explanation: @@ -698,7 +699,7 @@ Instead of: ------------------------------------------------------------------------------- -6.3.4. Enumerations, and #defines +4.3.4. Enumerations, and #defines Explanation: @@ -725,7 +726,7 @@ Example: ------------------------------------------------------------------------------- -6.3.5. Constants +4.3.5. Constants Explanation: @@ -751,9 +752,9 @@ Instead of: ------------------------------------------------------------------------------- -6.4. Using Space +4.4. Using Space -6.4.1. Put braces on a line by themselves. +4.4.1. Put braces on a line by themselves. Explanation: @@ -796,7 +797,7 @@ while ( more lines are read ) ------------------------------------------------------------------------------- -6.4.2. ALL control statements should have a block +4.4.2. ALL control statements should have a block Explanation: @@ -826,7 +827,7 @@ above also applies. ------------------------------------------------------------------------------- -6.4.3. Do not belabor/blow-up boolean expressions +4.4.3. Do not belabor/blow-up boolean expressions Example: @@ -842,7 +843,7 @@ knowledge of C/C++. (Hope I do not offend by that last comment ... 8-) ------------------------------------------------------------------------------- -6.4.4. Use white space freely because it is free +4.4.4. Use white space freely because it is free Explanation: @@ -862,7 +863,7 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) ------------------------------------------------------------------------------- -6.4.5. Don't use white space around structure operators +4.4.5. Don't use white space around structure operators Explanation: @@ -883,7 +884,7 @@ Instead of: aStruct -> aMember; aStruct . aMember; FunctionName (); ------------------------------------------------------------------------------- -6.4.6. Make the last brace of a function stand out +4.4.6. Make the last brace of a function stand out Example: @@ -914,7 +915,7 @@ of function comments. ------------------------------------------------------------------------------- -6.4.7. Use 3 character indentions +4.4.7. Use 3 character indentions Explanation: @@ -947,9 +948,9 @@ int function1( ... ) ------------------------------------------------------------------------------- -6.5. Initializing +4.5. Initializing -6.5.1. Initialize all variables +4.5.1. Initialize all variables Explanation: @@ -972,9 +973,9 @@ Status: developer-discretion if and only if the variable is assigned a value ------------------------------------------------------------------------------- -6.6. Functions +4.6. Functions -6.6.1. Name functions that return a boolean as a question. +4.6.1. Name functions that return a boolean as a question. Explanation: @@ -989,7 +990,7 @@ IsWebPageBlank(); ------------------------------------------------------------------------------- -6.6.2. Always specify a return type for a function. +4.6.2. Always specify a return type for a function. Explanation: @@ -999,7 +1000,7 @@ type if the function does not need to return anything. ------------------------------------------------------------------------------- -6.6.3. Minimize function calls when iterating by using variables +4.6.3. Minimize function calls when iterating by using variables Explanation: @@ -1039,7 +1040,7 @@ loop. ------------------------------------------------------------------------------- -6.6.4. Pass and Return by Const Reference +4.6.4. Pass and Return by Const Reference Explanation: @@ -1056,7 +1057,7 @@ should too. ------------------------------------------------------------------------------- -6.6.5. Pass and Return by Value +4.6.5. Pass and Return by Value Explanation: @@ -1069,7 +1070,7 @@ would not work. So, to be consistent, we should declare all prototypes with ------------------------------------------------------------------------------- -6.6.6. Names of include files +4.6.6. Names of include files Explanation: @@ -1094,7 +1095,7 @@ This duplicates the #include "file.h" behavior. ------------------------------------------------------------------------------- -6.6.7. Provide multiple inclusion protection +4.6.7. Provide multiple inclusion protection Explanation: @@ -1113,7 +1114,7 @@ Example: ------------------------------------------------------------------------------- -6.6.8. Use `extern "C"` when appropriate +4.6.8. Use `extern "C"` when appropriate Explanation: @@ -1136,7 +1137,7 @@ extern "C" ------------------------------------------------------------------------------- -6.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes +4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes Explanation: @@ -1159,9 +1160,9 @@ Status: Use with discretion. ------------------------------------------------------------------------------- -6.7. General Coding Practices +4.7. General Coding Practices -6.7.1. Turn on warnings +4.7.1. Turn on warnings Explanation @@ -1171,7 +1172,7 @@ possible. ------------------------------------------------------------------------------- -6.7.2. Provide a default case for all switch statements +4.7.2. Provide a default case for all switch statements Explanation: @@ -1211,7 +1212,7 @@ Status: Programmer discretion is advised. ------------------------------------------------------------------------------- -6.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: @@ -1230,7 +1231,7 @@ fall through and reason why you felt it was necessary. ------------------------------------------------------------------------------- -6.7.4. Use 'long' or 'short' Instead of 'int' +4.7.4. Use 'long' or 'short' Instead of 'int' Explanation: @@ -1244,7 +1245,7 @@ forget the exact typedefs now). Should we add these to IJB now that we have a ------------------------------------------------------------------------------- -6.7.5. Don't mix size_t and other types +4.7.5. Don't mix size_t and other types Explanation: @@ -1256,7 +1257,7 @@ can. ------------------------------------------------------------------------------- -6.7.6. Declare each variable and struct on its own line. +4.7.6. Declare each variable and struct on its own line. Explanation: @@ -1285,7 +1286,7 @@ Status: developer-discretion. ------------------------------------------------------------------------------- -6.7.7. Use malloc/zalloc sparingly +4.7.7. Use malloc/zalloc sparingly Explanation: @@ -1302,7 +1303,7 @@ list, then it should definitely be allocated via `malloc'. ------------------------------------------------------------------------------- -6.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: @@ -1328,7 +1329,7 @@ and freeing data structures (complex or nested). ------------------------------------------------------------------------------- -6.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: @@ -1341,7 +1342,7 @@ KILLPOPUPs, it is clear that it should come first. ------------------------------------------------------------------------------- -6.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: @@ -1366,11 +1367,11 @@ from the project). ------------------------------------------------------------------------------- -6.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.37 2002/04/26 17:23:29 swa Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.41 2002/05/04 08:44:44 swa Exp $"; /********************************************************************* * * File : $Source$ @@ -1427,7 +1428,7 @@ Example for file header comments: #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.41 2002/05/04 08:44:44 swa Exp $" /********************************************************************* * * File : $Source$ @@ -1518,13 +1519,13 @@ create a "self-documenting" web page. ------------------------------------------------------------------------------- -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. @@ -1553,7 +1554,7 @@ 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: @@ -1569,7 +1570,7 @@ Do not mail to the mailinglist (we cannot keep track on issues there). ------------------------------------------------------------------------------- -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 @@ -1582,24 +1583,59 @@ 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. -In the following text, 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 and increase or reset the RPM release number - in configure.in as appropriate. + * Increment the version number (point from odd to even in development + branches!) in configure.in. - * If the default actionsfile has changed since last release, bump up its - version info in this line: + * If default.action has changed since last release (i.e. software release or + standalone actions file release), bump up its version info to A.B in this + line: {+add-header{X-Actions-File-Version: A.B} -filter -no-popups} @@ -1607,17 +1643,26 @@ The following must be done by one of the developers prior to each new release. '$required_actions_file_version = "A.B";' * If the HTML documentation is not in sync with the SGML sources you need to - regenerate it. (If in doubt, just do it.) See the Section "Updating the - webserver" in this manual for details. + regenerate and upload it to the webserver. (If in doubt, just do it.) See + the Section "Updating the webserver" in this manual for details. * Commit all files that were changed in the above steps! * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. + * If the release was in a development branch, increase the point version from + even to odd (X.Y.(Z+1)) again in configure.in and commit your change. + + * On the webserver, copy the user manual to a new top-level directory called + X.Y.Z. This ensures that help links from the CGI pages, which have the + version as a prefix, will go into the right version of the manual. If this + is a development branch release, also symlink X.Y.(Z-1) to X.Y.Z and X.Y. + (Z+1) to . (i.e. dot). + ------------------------------------------------------------------------------- -8.2. Building and Releasing the Packages +6.3. Building and Releasing the Packages Now the individual packages can be built and released. Note that for GPL reasons the first package to be released is always the source tarball. @@ -1640,7 +1685,7 @@ platform dependent binary packages below. ------------------------------------------------------------------------------- -8.2.1. Source Tarball +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: @@ -1661,28 +1706,42 @@ change log field, use the relevant section of the ChangeLog file. ------------------------------------------------------------------------------- -8.2.2. 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. First, make sure that you have freshly exported the right version into an empty -directory. (See "Building and releasing packages" above). Then run: +directory. (See "Building and releasing packages" above). + +As the only exception to not changing anything after export from CVS, now +examine the file privoxy-dist.spec and make sure that the version information +and the RPM release number are correct. The RPM release numbers for each +version start at one. Hence it must be reset to one if this is the first RPM +for dist which is built from version X.Y.Z. Check the file list if unsure. +Else, it must be set to the highest already available RPM release number for +that version plus one. + +Then run: cd current autoheader && autoconf && ./configure Then do - make suse-dist (or make redhat-dist) + make dist-dist To upload the package to Sourceforge, simply issue - make suse-upload (or make redhat-upload) + make dist-upload rpm_packagerev -Go to the displayed URL and release the file publicly on Sourceforge. Use the -release notes and çhange log from the source tarball package. +where rpm_packagerev is the RPM release number as determined above. Go to the +displayed URL and release the file publicly on Sourceforge. Use the release +notes and change log from the source tarball package. ------------------------------------------------------------------------------- -8.2.3. OS/2 +6.3.3. OS/2 First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then get the OS/2 @@ -1717,7 +1776,7 @@ tarball package. ------------------------------------------------------------------------------- -8.2.4. Solaris +6.3.4. Solaris Login to Sourceforge's compilefarm via ssh: @@ -1741,7 +1800,7 @@ release notes and Change Log from the source tarball package. ------------------------------------------------------------------------------- -8.2.5. 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. @@ -1764,7 +1823,7 @@ release notes and Change Log from the source tarball package. ------------------------------------------------------------------------------- -8.2.6. Debian +6.3.6. Debian First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then, run: @@ -1776,7 +1835,7 @@ Then do FIXME. ------------------------------------------------------------------------------- -8.2.7. Mac OSX +6.3.7. Mac OSX First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then get the Mac OSX @@ -1806,7 +1865,7 @@ the release notes and Change Log from the source tarball package. ------------------------------------------------------------------------------- -8.2.8. FreeBSD +6.3.8. FreeBSD Login to Sourceforge's compilefarm via ssh: @@ -1830,7 +1889,7 @@ release notes and Change Log from the source tarball package. ------------------------------------------------------------------------------- -8.2.9. HP-UX 11 +6.3.9. HP-UX 11 First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then run: @@ -1842,7 +1901,7 @@ Then do FIXME. ------------------------------------------------------------------------------- -8.2.10. Amiga OS +6.3.10. Amiga OS First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then run: @@ -1854,7 +1913,7 @@ Then do FIXME. ------------------------------------------------------------------------------- -8.2.11. AIX +6.3.11. AIX Login to Sourceforge's compilefarm via ssh: @@ -1878,7 +1937,7 @@ release notes and Change Log from the source tarball package. ------------------------------------------------------------------------------- -8.3. Uploading and Releasing Your Package +6.4. Uploading and Releasing Your Package After the package is ready, it is time to upload it to SourceForge, and go through the release steps. The upload is done via FTP: @@ -1890,10 +1949,10 @@ through the release steps. The upload is done via FTP: * password: ijbswa-developers@lists.sourceforge.net Once this done go to http://sourceforge.net/project/admin/editpackages.php? -group_id=11118, making sure you are logged in. Find the your target platform in -the second column, and click Add Release. You will then need to create a new +group_id=11118, making sure you are logged in. Find your target platform in the +second column, and click Add Release. You will then need to create a new release for your package, using the format of $VERSION ($CODE_STATUS), e.g. -2.9.14 (beta). +2.9.15 (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 @@ -1909,7 +1968,7 @@ essentially the same steps, but select Edit Release, instead of Add Release. ------------------------------------------------------------------------------- -8.4. After the Release +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 @@ -1918,7 +1977,7 @@ change log. ------------------------------------------------------------------------------- -9. Update the Webserver +7. 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: @@ -1949,14 +2008,14 @@ avoid permission problems. ------------------------------------------------------------------------------- -10. 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 the following sections. ------------------------------------------------------------------------------- -10.1. Get Support +8.1. Get Support To get support, use the Sourceforge Support Forum: @@ -1964,7 +2023,7 @@ To get support, use the Sourceforge Support Forum: ------------------------------------------------------------------------------- -10.2. Report bugs +8.2. Report bugs To submit bugs, use the Sourceforge Bug Forum: @@ -1981,7 +2040,7 @@ reproduce the bug. ------------------------------------------------------------------------------- -10.3. Request new features +8.3. Request new features To submit ideas on new features, use the Sourceforge feature request forum: @@ -1989,7 +2048,7 @@ To submit ideas on new features, use the Sourceforge feature request forum: ------------------------------------------------------------------------------- -10.4. Report ads or other filter problems +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 @@ -2001,7 +2060,7 @@ your feedback. These will be announced on the ijbswa-announce list. ------------------------------------------------------------------------------- -10.5. Other +8.5. Other For any other issues, feel free to use the mailing lists: @@ -2013,9 +2072,19 @@ too. See the page on Sourceforge. ------------------------------------------------------------------------------- -11. Copyright and History +9. Copyright, License and History + +9.1. Copyright + +Permission is granted to copy, distribute and/or modify this document under the +terms of the GNU Free Documentation License, Version 1.1 or any later version +published by the Free Software Foundation with no Invariant Sections, no +Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found +http://www.gnu.org/licenses/fdl.html. + +------------------------------------------------------------------------------- -11.1. Copyright +9.2. 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 @@ -2034,7 +2103,7 @@ Place, Suite 330, Boston, MA 02111-1307 USA. ------------------------------------------------------------------------------- -11.2. History +9.3. History Privoxy is evolved, and derived from, the Internet Junkbuster, with many improvments and enhancements over the original. @@ -2048,7 +2117,7 @@ grown whiskers ;-). ------------------------------------------------------------------------------- -12. See also +10. See also Other references and sites of interest to Privoxy users: