X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=362b5f5bbbc26e6173bc67aba9a7fdc9410905e7;hb=be490aaf495531c679f5eec40c2f548ff3d56d2c;hp=8b36ac4351d21810bd9edd87e6d2d7478e9bedcc;hpb=e70110618027c7cb90164df41ae9b5fefb6ef5ac;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 8b36ac43..362b5f5b 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,9 +8,9 @@ - - - + + + @@ -23,14 +23,16 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $ - Copyright (C) 2001, 2002 Privoxy Developers + Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org See LICENSE. ======================================================================== NOTE: Please read developer-manual/documentation.html before touching - anything in this, or other Privoxy documentation. + anything in this, or other Privoxy documentation. You have been warned! + Failure to abide by this rule will result in the revocation of your license + to live a peaceful existence! ======================================================================== --> @@ -42,13 +44,13 @@ - Copyright &my-copy; 2001, 2002 by + Copyright &my-copy; 2001-2006 by Privoxy Developers - $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $ - + @@ -93,6 +95,8 @@ Hal. + Please note that this document is constantly evolving. This copy represents + the state at the release of version &p-version;. You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/. Please see the Contact section @@ -129,6 +133,7 @@ Hal. Quickstart to Privoxy Development + + + The first step is to join the developer's mailing list. + You can submit your ideas, or even better patches. Patches are best + submitted to the Sourceforge tracker set up for this purpose, but + can be sent to the list for review too. + - For the time being (read, this section is under construction), please - refer to the extensive comments in the source code. + You will also need to have a cvs package installed, which will + entail having ssh installed as well (which seems to be a requirement of + SourceForge), in order to access the cvs repository. Having the GNU build + tools is also going to be important (particularly, autoconf and gmake). + + + For the time being (read, this section is under construction), you can + also refer to the extensive comments in the source code. In fact, + reading the code is recommended in any case. @@ -146,9 +166,10 @@ Hal. 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. + If you become part of the active development team, you will eventually + need write access to our holy grail, the CVS repository. One of the + team members will need to set this up for you. Please read + this chapter completely before accessing via CVS. Access to CVS @@ -159,22 +180,72 @@ Hal. 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.cvs.sourceforge.net, the repository is called ijbswa, and the source tree module is called current. - CVS Commit Guideline + + Branches + + Within the CVS repository, there are modules and branches. As + mentioned, the sources are in the current + module. Other modules are present for platform specific + issues. There is a webview of the CVS hierarchy at http://ijbswa.cvs.sourceforge.net/ijbswa/, + which might help with visualizing how these pieces fit together. + + + Branches are used to fork a sub-development path from the main trunk. + Within the current module where the sources are, there + is always at least one branch from the main trunk + devoted to a stable release series. The main trunk is where active + development takes place for the next stable series (e.g. 3.2.x). + So just prior to each stable series (e.g. 3.0.x), a branch is created + just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). + Once the initial stable release of any stable branch has taken place, + this branch is only used for bugfixes, which have + had prior testing before being committed to CVS. (See Version Numbers below for details on + versioning.) + + + At one time there were two distinct branches: stable and unstable. The + more drastic changes were to be in the unstable branch. These branches + have now been merged to minimize time and effort of maintaining two + branches. + + + + + CVS Commit Guidelines 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: + times. There are differing guidelines for the stable branch and the + main development trunk, and we ask anyone with CVS access to strictly + adhere to the following guidelines: + + + + Basic Guidelines, for all branches: + + - Never (read: never, ever) be tempted to commit - that small change without testing it thoroughly first. When we're + Please don't commit even + a small change without testing it thoroughly first. When we're close to a public release, ask a fellow developer to review your changes. @@ -195,42 +266,63 @@ Hal. 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). + with the team's general consensus on what should be done. + + + Note that near a major public release, we get more cautious. + There is always the possibility to submit a patch to the patch + tracker instead. + + - - - Discussing Changes First + + + @@ -246,7 +338,8 @@ Hal. url="../user-manual/index.html">user-manual, FAQ, and, of course this, the developer-manual in this format. - The README, AUTHORS + The README, AUTHORS, + INSTALL, privoxy.1 (man page), and config files are also now maintained as Docbook SGML. These files, when built, in the top-level source directory are @@ -254,8 +347,7 @@ Hal. variation on this file, privoxy-index.html, meant for inclusion with doc packages), are maintained as SGML as well. DO NOT edit these directly. Edit the SGML source, or - contact someone involved in the documentation (at present Stefan and - Hal). + contact someone involved in the documentation. config requires some special handling. The reason it @@ -268,18 +360,17 @@ Hal. which should be reviewed for errors and mis-formatting. Once satisfied that it is correct, then it should be hand copied to config. - - Other, less formal documents (e.g. LICENSE, - INSTALL) are maintained as plain text files in the - top-level source directory. At least for the time being. + Other, less formal documents (e.g. LICENSE) are + maintained as plain text files in the top-level source directory. Packagers are encouraged to include this documentation. For those without the ability to build the docs locally, text versions of each are kept in - CVS. HTML versions are also now being kept in CVS under - doc/webserver/*. + CVS. HTML versions are also being kept in CVS under + doc/webserver/*. And PDF version are kept in + doc/pdf/*. Formal documents are built with the Makefile targets of @@ -301,7 +392,8 @@ Hal. First, build the docs by running make dok (or alternately make - redhat-dok). + redhat-dok). For PDF docs, do make + dok-pdf. Run make webserver which copies all @@ -411,7 +503,7 @@ Hal. You might also find Writing Documentation + url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation Using DocBook - A Crash Course useful. @@ -499,7 +591,7 @@ Hal. Our documents are available in differing formats. Right now, they - are just plain text, and HTML, but PDF, and others is always a + are just plain text, HTML, and PDF, but others are always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake: @@ -1740,14 +1832,14 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1769,8 +1861,9 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31: * The GNU General Public License should be included with * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html - * or write to the Free Software Foundation, Inc., 59 - * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -1800,14 +1893,14 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $" /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1829,8 +1922,9 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; * The GNU General Public License should be included with * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html - * or write to the Free Software Foundation, Inc., 59 - * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -1978,7 +2072,7 @@ at sourceforge. Three simple steps: 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: + separated by dots, like in X.Y.Z (e.g. 3.0.0), where: @@ -2017,9 +2111,43 @@ at sourceforge. Three simple steps: This ensures that builds from CVS snapshots are easily distinguished from released versions. The point version is reset to zero when the minor changes. + + Stable branches work a little differently, since there should be + little to no development happening in such branches. Remember, + only bugfixes, which presumably should have had some testing + before being committed. Stable branches will then have their + version reported as 0.0.0, during that period + between releases when changes are being added. This is to denote + that this code is not for release. Then + as the release nears, the version is bumped according: e.g. + 3.0.1 -> 0.0.0 -> 3.0.2. + + + In summary, the main CVS trunk is the development branch where new + features are being worked on for the next stable series. This should + almost always be where the most activity takes place. There is always at + least one stable branch from the trunk, e.g now it is + 3.0, which is only used to release stable versions. + Once the initial *.0 release of the stable branch has been done, then as a + rule, only bugfixes that have had prior testing should be committed to + the stable branch. Once there are enough bugfixes to justify a new + release, the version of this branch is again incremented Example: 3.0.0 + -> 3.0.1 -> 3.0.2, etc are all stable releases from within the stable + branch. 3.1.x is currently the main trunk, and where work on 3.2.x is + taking place. If any questions, please post to the devel list + before committing to a stable branch! + + + Developers should remember too that if they commit a bugfix to the stable + branch, this will more than likely require a separate submission to the + main trunk, since these are separate development trees within CVS. If you + are working on both, then this would require at least two separate check + outs (i.e main trunk, and the stable release branch, + which is v_3_0_branch at the moment). + @@ -2042,7 +2170,8 @@ at sourceforge. Three simple steps: Increment the version number (point from odd to even in development - branches!) in configure.in. + branches!) in configure.in. (RPM spec files + will need to be incremented as well.) @@ -2063,12 +2192,37 @@ at sourceforge. Three simple steps: - If the HTML documentation is not in sync with the SGML sources - you need to regenerate and upload it to the webserver. (If in - doubt, just do it.) See the Section "Updating the webserver" in - this manual for details. + All documentation should be rebuild after the version bump. + Finished docs should be then be committed to CVS (for those + without the ability to build these). Some docs may require + rather obscure processing tools. config, + the man page (and the html version of the man page), and the PDF docs + fall in this category. REAMDE, the man page, AUTHORS, and config + should all also be committed to CVS for other packagers. The + formal docs should be uploaded to the webserver. See the + Section "Updating the webserver" in this manual for details. + + + The User Manual is also used for context + sensitive help for the CGI editor. This is version sensitive, so that + the user will get appropriate help for his/her release. So with + each release a fresh version should be uploaded to the webserver + (this is in addition to the main User Manual + link from the main page since we need to keep manuals for various + versions available). The CGI pages will link to something like + http://privoxy.org/$(VERSION)/user-manual/. This + will need to be updated for each new release. There is no Makefile + target for this at this time!!! It needs to be done manually. + + + + + All developers should look at the ChangeLog and + make sure noteworthy changes are referenced. + + Commit all files that were changed in the above steps! @@ -2112,15 +2266,16 @@ at sourceforge. Three simple steps: 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:. + the right version from CVS into an empty directory (just press return when + asked for a password): 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 + cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login + cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current @@ -2131,6 +2286,17 @@ at sourceforge. Three simple steps: on exactly the same code. + + + Every significant release of Privoxy has included at least one + package that either had incorrect versions of files, missing files, + or incidental leftovers from a previous build process that gave + unknown numbers of users headaches to try to figure out what was + wrong. PLEASE, make sure you are using pristene sources, and are + following the prescribed process! + + + Please find additional instructions for the source tarball and the individual platform dependent binary packages below. And details @@ -2215,15 +2381,22 @@ at sourceforge. Three simple steps: - user.action is designed for local preferences. - Make sure this does not get overwritten! + user.action and user.filter + are designed for local preferences. Make sure these do not get overwritten! + config should not be overwritten either. This + has especially important configuration data in it. + trust should be left in tact as well. - Other configuration files should be installed as the new defaults, - but all previously installed configuration files should be preserved - as backups. This is just good manners :-) + Other configuration files (default.action, + default.filter and + standard.action) should be installed as the new + defaults, but all previously installed configuration files should be + preserved as backups. This is just good manners :-) These files are + likely to change between releases and contain important new features + and bug fixes. @@ -2235,6 +2408,15 @@ at sourceforge. Three simple steps: maintainers to do this if you can't). + + + Packagers should do a clean install of their + package after building it. So any previous installs should be + removed first to ensure the integrity of the newly built package. + Then run the package for a while to make sure there are no + obvious problems, before uploading. + + @@ -2339,7 +2521,7 @@ at sourceforge. Three simple steps: - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup + cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup @@ -2439,7 +2621,7 @@ at sourceforge. Three simple steps: - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup + cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup @@ -2503,7 +2685,7 @@ at sourceforge. Three simple steps: - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup + cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup @@ -2715,7 +2897,10 @@ at sourceforge. Three simple steps: mailing list, Subject: "Version X.Y.Z available for download". Be sure to include the download - location, the release notes and the change log. + location, the release notes and the Changelog. Also, post an + updated News item on the project page Sourceforge, and update the Home + page and docs linked from the Home page (see below). Other news sites + and release oriented sites, such as Freshmeat, should also be notified. @@ -2724,31 +2909,33 @@ at sourceforge. Three simple steps: Update the Webserver - When updating the webserver, please follow these steps to make - sure that no broken links, inconsistent contents or permission - problems will occur: + The webserver should be updated at least with each stable release. When + updating, please follow these steps to make sure that no broken links, + inconsistent contents or permission problems will occur (as it has many + times in the past!): - If you have changed anything in the documentation source SGML files, - do: + If you have changed anything in the stable-branch documentation source + SGML files, do: - make dok # (or make redhat-dok if make dok doesn't work for you) + make dok dok-pdf # (or 'make redhat-dok dok-pdf' 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/faq, + doc/pdf/*.pdf and doc/webserver/index.html automatically. - If you changed the manual page source, generate + If you changed the manual page sources, 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.) + a separate target due to dependencies on some obscure perl scripts + [now in CVS, but not well tested]. See comments in GNUmakefile.) If you want to add new files to the webserver, create them locally in @@ -2756,7 +2943,8 @@ at sourceforge. Three simple steps: create new directories under doc/webserver). - Next, commit any changes from the above steps to CVS. All set? Then do + Next, commit any changes from the above steps to CVS. All set? + If these are docs in the stable branch, then do: @@ -2770,7 +2958,9 @@ at sourceforge. Three simple steps: Please do NOT use any other means of transferring - files to the webserver to avoid permission problems. + files to the webserver to avoid permission problems. Also, please do not + upload docs from development branches or versions. The publicly posted + docs should be in sync with the last official release. @@ -2835,21 +3025,53 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ - Revision 1.50 2002/06/05 00:31:55 hal9 - Mass commit for new entities, most significantly so docs can read version - and code status info from tmp files, so perl is no longer used. Also, docs can - differentiate on alpha -> beta -> stable now. + Revision 2.10 2006/09/22 01:27:55 hal9 + Final commit of probably various minor changes here and there. Unless + something changes this should be ready for pending release. + + Revision 2.9 2006/09/14 02:30:07 hal9 + Fix ijbswa cvs links. Update notes on release process, and which config files + should be overwritten and which not. + + Revision 2.8 2006/08/22 23:35:01 hal9 + Fix email address, cvs URI, address branching changes and various other + small updates. + + Revision 2.7 2006/07/18 14:48:50 david__schmidt + Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch) + with what was really the latest development (the v_3_0_branch branch) + + Revision 1.46.2.11 2002/12/11 13:12:15 hal9 + Rewrite cvs write access give-away section. + + Revision 1.46.2.10 2002/09/26 21:53:45 hal9 + Changes to reflect recent change in stable branch commit policy (hopefully + clearer now). + + Revision 1.46.2.9 2002/09/26 01:21:40 hal9 + Porting 3.1.1 changes: more on cvs and branches, more on versions and + releases. + + Revision 1.46.2.8 2002/08/17 00:16:10 hal9 + Add note on updating webserver for User-manual/CGI editor, which is version + dependent (and different from main UM link). + + Revision 1.46.2.7 2002/08/14 17:29:25 hal9 + Add small notes on post-release steps, and uploading docs to webserver. + + Revision 1.46.2.6 2002/08/10 11:40:25 oes + Added disclaimer about probably being out-of-date and two small hints - Revision 1.49 2002/06/03 00:28:16 hal9 - Sync with various changes from 3.0 branch. Add two new files for config stuff. + Revision 1.46.2.5 2002/08/09 01:15:12 hal9 + Added some notes on pre-release steps (test builds first, update ChangeLog). - Revision 1.51 2002/05/29 00:30:59 mal0rd + Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd Fixed a little formatting. Clarified debian section. - Revision 1.50 2002/05/28 04:32:45 hal9 + Revision 1.46.2.3 2002/05/28 04:32:45 hal9 Change hints on bundling index.html to privoxy-index.html - Revision 1.49 2002/05/26 17:04:24 hal9 + Revision 1.46.2.2 2002/05/26 17:04:24 hal9 -Spellcheck, very minor edits, and sync across branches Revision 1.48 2002/05/26 12:48:31 roro