X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=bede0f141552b8b8cba7b28acda2e1b5dbe10710;hp=8a0b041b5a6cb09e6098f51a4281cc646479c99a;hb=c69d5ea9f898a4e78c7c6efee2ace772bcdce5c9;hpb=9c0440416d2af8c052d5d1941afbec22b6d68125 diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 8a0b041b..bede0f14 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -1,5 +1,5 @@ + @@ -7,7 +7,7 @@ - + @@ -21,7 +21,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.29 2002/04/10 18:45:14 swa Exp $ + $Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $ Written by and Copyright (C) 2001 the SourceForge Privoxy team. http://www.privoxy.org/ @@ -44,7 +44,7 @@ Privoxy Developer Manual - $Id: developer-manual.sgml,v 1.29 2002/04/10 18:45:14 swa Exp $ + $Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $ @@ -72,14 +72,16 @@ - &p-intro; + 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. + Please see the Contact section + on how to contact the developers. @@ -124,38 +126,112 @@ 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. - + 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. + + - -For the time being (read, this section is under construction), please note the -following guidelines for changing stuff in the code. If it is - - - 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 - - - - + + 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. + + + 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.. + + + ..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 + 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), @@ -177,7 +253,7 @@ following guidelines for changing stuff in the code. If it is Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as plain text files in the - toplevel source directory. At least for the time being. + top-level source directory. At least for the time being. Packagers are encouraged to include this documentation. For those without @@ -196,7 +272,7 @@ following guidelines for changing stuff in the code. If it is Documentation writers should please make sure documents build - successfully before committing to CVS. + successfully before committing to CVS, if possible. How do you update the webserver (i.e. the pages on privoxy.org)? @@ -215,6 +291,15 @@ following guidelines for changing stuff in the code. If it is + + 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). + @@ -260,51 +345,57 @@ following guidelines for changing stuff in the code. If it is 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></literllayout>, like - <pre>, more or less. - - - <itemizedlist></itemizdelist>, 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. - - + + + + <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 @@ -374,13 +465,14 @@ following guidelines for changing stuff in the code. If it is We have an international audience. Refrain from slang, or English - idiosyncrasies (too many to list :). + 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 lenghty URLs for + for obvious reasons. This is not always possible, with lengthy URLs for instance. @@ -448,7 +540,7 @@ following guidelines for changing stuff in the code. If it is - Re-cyclable boilerplate text entities are defined like: + Re- boilerplate text entities are defined like: <!entity supported SYSTEM "supported.sgml"> @@ -469,15 +561,15 @@ following guidelines for changing stuff in the code. If it is p-version: the Privoxy - version string, e.g. 2.9.13. + version string, e.g. &p-version;. p-status: the project status, either - ALPHA, BETA, or STABLE. + alpha, beta, or stable. p-not-stable: use to conditionally include - text in not stable releases (e.g. BETA). + text in not stable releases (e.g. beta). p-stable: just the opposite. @@ -597,7 +689,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. @@ -743,7 +835,7 @@ 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. @@ -770,7 +862,7 @@ 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. @@ -912,11 +1004,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: @@ -978,7 +1070,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-) @@ -1059,14 +1151,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. @@ -1134,7 +1226,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. @@ -1287,7 +1379,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. @@ -1360,9 +1452,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. @@ -1408,7 +1500,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 ) ) */ @@ -1419,7 +1511,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. @@ -1516,7 +1608,7 @@ long c = 0; on 1 line. You should, although, provide a good comment on their functions. - Status: developer-discrection. + Status: developer-discretion. @@ -1526,7 +1618,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 @@ -1535,7 +1627,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'. @@ -1551,7 +1643,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: @@ -1564,7 +1656,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). @@ -1591,16 +1683,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: @@ -1615,7 +1707,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). @@ -1628,7 +1720,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.29 2002/04/10 18:45:14 swa Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $"; /********************************************************************* * * File : $Source$ @@ -1680,7 +1772,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. @@ -1688,7 +1780,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.29 2002/04/10 18:45:14 swa Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $" /********************************************************************* * * File : $Source$ @@ -1784,13 +1876,6 @@ int FUNCTION_NAME( void *param1, const char *x ) - - Version Control Guidelines - To be filled. note on cvs comments. Don't only comment what you did, - but also why you did it! - - - Testing Guidelines To be filled. @@ -1847,20 +1932,29 @@ at sourceforge. Three simple steps: - Releasing a new version + Releasing a New Version - To minimize trouble with distribution contents, webpage - 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. + 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), -gmake (GNU's version of make), autoconf, cvs, ???. + ncftpput (ncftp), 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): + In the following text, replace X, Y and Z with the actual version number + (X = major, Y = minor, Z = point): @@ -1880,130 +1974,161 @@ at sourceforge. Three simple steps: - Increment the version number in configure.in in - CVS. Also, inrease 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 and increase or reset the RPM release number + in configure.in as appropriate. - If the default actionsfile has changed since last release, - bump up its version info in this line: + If the default actionsfile has changed since last + release, bump up its version info 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 it. (If in doubt, just do it.) See the + Section "Updating the webserver" in this manual for details. + - 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. + Commit all files that were changed in the above steps! - The first package uploaded should be the official - tarball release. This is built with the - make tarball-dist Makefile - target, and then can be uploaded with - make tarball-upload (see below). + 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. - Update the webserver - - 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 + + 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. + + + 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: - - make webserver - + + cd current + autoheader && autoconf && ./configure + - Note that make dok - (or make redhat-dok) creates - doc/webserver/user-manual, - doc/webserver/developer-manual, - doc/webserver/faq and - doc/webserver/man-page automatically. - - - 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. - - - - SuSE or Red Hat - - Ensure that you have the latest code version. Hence run: + Then do: - 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 - + make tarball-dist + - first. + 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 or Red Hat + + 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 suse-dist or make redhat-dist - + make suse-dist (or make redhat-dist) + To upload the package to Sourceforge, simply issue - make suse-upload or make redhat-upload - + make suse-upload (or make redhat-upload) + Go to the displayed URL and release the file publicly on Sourceforge. + Use the release notes and çhange log from the source tarball package. - + - OS/2 + 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 - + You will need a mix of development tools. @@ -2019,55 +2144,58 @@ at sourceforge. Three simple steps: 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 - - And in the ./files directory you will have the - WarpIN-installable executable. - Upload this anonymously to - uploads.sourceforge.net/incoming, create a release - for it, and you're done. + - + + 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 + 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, + 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: - 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: - - - autoheader && autoconf && ./configure - + Then run @@ -2075,81 +2203,88 @@ at sourceforge. Three simple steps: 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. + the file publicly. Use the release notes and Change Log from the + source tarball package. - + - Windows + Windows - 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 - - - - Run: - - - - autoheader && autoconf && ./configure - - - - Then do FIXME. - - + 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 + Debian - 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, 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: - - - autoheader && autoconf && ./configure - + Then do FIXME. - + - Mac OSX + 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 - + + + + Then run: - From the osxsetup directory, run: + cd osxsetup build - + This will run autoheader, autoconf and @@ -2162,49 +2297,40 @@ at sourceforge. Three simple steps: 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. + create a release for it, and you're done. Use the release notes + and Change Log from the source tarball package. - + - FreeBSD - - Change the version number of Privoxy in the - configure.in file. Run: - - autoheader && autoconf && ./configure - - Then ... - + 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: - 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: - - - autoheader && autoconf && ./configure - + Then run: @@ -2212,133 +2338,71 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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. + the file publicly. Use the release notes and Change Log from the + source tarball package. - + - Tarball + HP-UX 11 - Ensure that you have the right 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 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: - - - - autoheader && autoconf && ./configure - - - - Then do: - - - - make tarball-dist - - - - To upload the package to Sourceforge, simply issue - - - - make tarball-upload - - - - Goto the displayed URL and release the file publicly on Sourceforge. - - - - HP-UX 11 - - 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: - - - autoheader && autoconf && ./configure - + Then do FIXME. - + - Amiga OS + Amiga OS - 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 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: - - - autoheader && autoconf && ./configure - + Then do FIXME. - + - AIX + AIX Login to Sourceforge's compilefarm via ssh: ssh cf.sourceforge.net - + - Choose the right operating system. If you have downloaded Privoxy - before: + 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: - 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: - - - autoheader && autoconf && ./configure - + Then run: @@ -2346,18 +2410,138 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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. + 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 + + + + + + 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. + + + + 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 @@ -2411,6 +2595,35 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 1.37 2002/04/26 17:23:29 swa + bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot + + Revision 1.36 2002/04/26 05:25:23 hal9 + Mass commit to catch a few scattered fixes. + + Revision 1.35 2002/04/17 15:16:15 oes + Added link to docbook crash course + + Revision 1.34 2002/04/15 23:39:32 oes + - Extended & fixed the release section + - Added CVS guideline sections + - Separated webserver section from release section + - Commented out boilerplate inclusion (If you don't know yet what it is, + you shouldn't mess with its code ;-) + - Nits & fixes + + Revision 1.33 2002/04/12 03:49:53 hal9 + Spell checked. Clarification on where docs are kept. + + Revision 1.32 2002/04/11 21:29:58 jongfoster + Documenting Win32 release procedure + + Revision 1.31 2002/04/11 09:32:52 oes + more nits + + Revision 1.30 2002/04/11 09:24:53 oes + nits + Revision 1.29 2002/04/10 18:45:14 swa generated