X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=786fdd0b3ba981aba6a7dbb43834732db61d1c63;hb=d7900699eb8ddd647aa6ac52c2a048ba3c130113;hp=a35db57d014275b07413fa8fea5d5ba8827340fd;hpb=82ca06f718357047cf1b171ac663d080cb2b1271;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index a35db57d..786fdd0b 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -21,7 +21,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $ + $Id: developer-manual.sgml,v 1.34 2002/04/15 23:39:32 oes 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.32 2002/04/11 21:29:58 jongfoster Exp $ + $Id: developer-manual.sgml,v 1.34 2002/04/15 23:39:32 oes Exp $ @@ -72,7 +72,8 @@ - &p-intro; + @@ -126,35 +127,105 @@ 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. + url="http://sourceforge.net/">Sourceforge to support our + development. Mail your ID to the list and wait until a + project manager has added you. For the time being (read, this section is under construction), please - note the following guidelines for changing stuff in the code. If it is - - - 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 - - + refer to the extensive comments in the source code. + + + + The CVS Repository - Note that near a major public release, we get a bit more cautious - if - unsure, it doesn't hurt to ask first. + 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. + + @@ -230,7 +301,6 @@ updated (this is done just prior to a new release). - Quickstart to Docbook and SGML @@ -275,51 +345,57 @@ 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. - - + + + + <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 @@ -1644,7 +1720,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.34 2002/04/15 23:39:32 oes Exp $"; /********************************************************************* * * File : $Source$ @@ -1704,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.32 2002/04/11 21:29:58 jongfoster Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.34 2002/04/15 23:39:32 oes Exp $" /********************************************************************* * * File : $Source$ @@ -1800,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. @@ -1863,20 +1932,29 @@ at sourceforge. Three simple steps: - Releasing a new version + Releasing a New Version + + When we release versions of Privoxy, + our work leaves our cozy secret lab and has to work in the cold + RealWorld[tm]. Once it is released, there is no way to call it + back, so it is very important that great care is taken to ensure + that everything runs fine, and not to introduce problems in the + very last minute. + - To minimize trouble with distribution contents, web-page - errors and the like, we strongly encourage you - to follow this section if you prepare a new release of - code or new pages on the webserver. + So when releasing a new version, please adhere exactly to the + procedure outlined in this chapter. + The following programs are required to follow this process: - ncftpput (ncftp), scp (ssh), -gmake (GNU's version of make), autoconf, cvs, ???. + 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): @@ -1896,14 +1974,8 @@ at sourceforge. Three simple steps: - Increment the version number in configure.in in - CVS. Also, increase or reset the RPM release number in - configure.in as appropriate. Do NOT - touch version information after export from CVS. - All packages will use the version and release data - from configure.in. - Local files should not be changed, except prior to a CVS commit!!! - This way we are all on the same page! + Increment the version number and increase or reset the RPM release number + in configure.in as appropriate. @@ -1920,6 +1992,13 @@ at sourceforge. Three simple steps: 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. + @@ -1933,76 +2012,88 @@ at sourceforge. Three simple steps: Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. - - - The first package uploaded should be the official - tarball release, as required by the GPL. This is built - with the make tarball-dist Makefile - target, and then can be uploaded with - make tarball-upload (see below). - - - 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 - - - - make webserver - - - - This will do the upload to the webserver (www.privoxy.org). + + 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. + - Note that make dok - (or make redhat-dok) creates - doc/webserver/user-manual, - doc/webserver/developer-manual, - doc/webserver/faq and - doc/webserver/index.html automatically. - (doc/webserver/man-page/privoxy-man-page.html - is created by a separate Makefile target, make - man, due to dependencies on some obscure perl scripts. - See comments in GNUmakefile.) - - - Someone should also commit these to CVS so that packagers without the - ability to build docs locally, have access to them. This is a separate - step, and should also be done before each official release. + 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:. - + - 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. - - + + 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. + - SuSE or Red Hat - - Ensure that you have the latest code version. Hence run: + 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: - 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 + autoheader && autoconf && ./configure + + + + Then do: + + + + make tarball-dist + + + + To upload the package to Sourceforge, simply issue + + + + make tarball-upload - first. + 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 @@ -2011,7 +2102,7 @@ at sourceforge. Three simple steps: - make suse-dist or make redhat-dist + make suse-dist (or make redhat-dist) @@ -2024,18 +2115,18 @@ at sourceforge. Three simple steps: 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 @@ -2053,29 +2144,41 @@ 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: @@ -2083,23 +2186,14 @@ at sourceforge. Three simple steps: - 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 @@ -2115,32 +2209,27 @@ at sourceforge. Three simple steps: 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 You should ensure you have the latest version of Cygwin (from http://www.cygwin.com/). Run the following commands from within a Cygwin bash shell. - First check out a clean copy of the correct code version, by running: + 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: - mkdir dist - cd dist - cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z . + cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup - - (Note: It is important that this is a clean copy of the code, - do not re-use a working directory after you have manually compiled - there). - Then you can build the package. This is fully automated, and is controlled by winsetup/GNUmakefile. @@ -2155,49 +2244,45 @@ at sourceforge. Three simple steps: Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and upload it to - SourceForge. + 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 - From the osxsetup directory, run: + Then run: + + + cd osxsetup build @@ -2212,24 +2297,21 @@ 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: @@ -2240,19 +2322,13 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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 @@ -2268,99 +2344,46 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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. - - - - Tarball - - Ensure that you have the right 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: - - - - make tarball-dist - - - - To upload the package to Sourceforge, simply issue + the file publicly. Use the release notes and Change Log from the + source tarball package. - - - make tarball-upload - - - - Goto the displayed URL and release the file publicly on Sourceforge. - - + - HP-UX 11 + HP-UX 11 - 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. - + - 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: @@ -2370,23 +2393,14 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg - 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 @@ -2402,12 +2416,79 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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. - + + + + + 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 @@ -2461,6 +2542,17 @@ 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.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