X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=8b36ac4351d21810bd9edd87e6d2d7478e9bedcc;hp=89c126426ae735e08c5adc25f6a46fd9bed6e92d;hb=e70110618027c7cb90164df41ae9b5fefb6ef5ac;hpb=47b73971a4fed5f577628fde3ad12e751b98c53b diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 89c12642..8b36ac43 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,9 +8,9 @@ - - - + + + @@ -23,16 +23,14 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $ + $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ Copyright (C) 2001, 2002 Privoxy Developers See LICENSE. ======================================================================== NOTE: Please read developer-manual/documentation.html before touching - 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! + anything in this, or other Privoxy documentation. ======================================================================== --> @@ -50,7 +48,7 @@ - $Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $ + $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ - + @@ -81,10 +79,11 @@ Hal. ]]> - The developer manual gives the users information on how to help the developer - team. It provides guidance on coding, testing, documentation and other - issues. - + The developer manual provides guidance on coding, testing, packaging, documentation + and other issues of importance to those involved with + Privoxy development. It is mandatory (and helpful!) reading + for anyone who wants to join the team. + @@ -190,8 +189,8 @@ Hal. 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. + all changes are committed (e.g. when changing the signature of a function), + then commit all files one after another, without long delays in between. If necessary, prepare the commit messages in advance. @@ -207,7 +206,7 @@ Hal. 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 bug-fix / clean-up / cosmetic thing: shoot ..a new feature that can be turned off: shoot @@ -248,14 +247,29 @@ Hal. FAQ, and, of course this, the developer-manual in this format. The README, AUTHORS - privoxy.1 (man page) files are also now maintained - as Docbook SGML. The finished files are all in the top-level source - directory are generated files! Also, index.html, the - Privoxy home page, is maintained as SGML. + 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 + generated files! Also, the Privoxy index.html (and a + 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). + + config requires some special handling. The reason it + is maintained this way is so that the extensive comments in the file + mirror those in user-manual. But the conversion + process requires going from SGML to HTML to text to special formatting + required for the embedded comments. Some of this does not survive so + well. Especially some of the examples that are longer than 80 characters. + The build process for this file outputs to config.new, + 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 @@ -1649,7 +1663,7 @@ list, then it should definitely 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 accommodate this. + free/unload/destructor type function to accommodate this. Example: @@ -1726,7 +1740,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -1786,7 +1800,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.43 2002/05/10 01:48:19 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $" /********************************************************************* * * File : $Source$ @@ -1931,7 +1945,7 @@ at sourceforge. Three simple steps: intelligent (keep it short and precise). - Do not mail to the mailinglist (we cannot keep track on issues there). + Do not mail to the mailing list (we cannot keep track on issues there). @@ -1980,12 +1994,12 @@ at sourceforge. Three simple steps: 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 + being added and only bug-fixes 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 + The minor is reset to zero (and one) when the major is incremented. 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. @@ -2123,6 +2137,110 @@ at sourceforge. Three simple steps: on the Sourceforge release process below that. + + Note on Privoxy Packaging + + Please keep these general guidelines in mind when putting together + your package. These apply to all platforms! + + + + + + Privoxy requires + write access to: all *.action files, all + logfiles, and the trust file. You will + need to determine the best way to do this for your platform. + + + + + Please include up to date documentation. At a bare minimum: + + + + LICENSE (top-level directory) + + + + + README (top-level directory) + + + + + AUTHORS (top-level directory) + + + + + man page (top-level directory, Unix-like + platforms only) + + + + + The User Manual (doc/webserver/user-manual/) + + + + + FAQ (doc/webserver/faq/) + + + + Also suggested: Developer Manual + (doc/webserver/developer-manual) and ChangeLog + (top-level directory). FAQ and the manuals are + HTML docs. There are also text versions in + doc/text/ which could conceivably also be + included. + + + The documentation has been designed such that the manuals are linked + to each other from parallel directories, and should be packaged + that way. privoxy-index.html can also be + included and can serve as a focal point for docs and other links of + interest (and possibly renamed to index.html). + This should be one level up from the manuals. There is a link also + on this page to an HTMLized version of the man page. To avoid 404 for + this, it is in CVS as + doc/webserver/man-page/privoxy-man-page.html, + and should be included along with the manuals. There is also a + css stylesheets that can be included for better presentation: + p_doc.css. This should be in the same directory + with privoxy-index.html, (i.e. one level up from + the manual directories). + + + + + user.action is designed for local preferences. + Make sure this does not get overwritten! + + + + + Other configuration files should be installed as the new defaults, + but all previously installed configuration files should be preserved + as backups. This is just good manners :-) + + + + + Please check platform specific notes in this doc, if you haven't + done Privoxy packaging before for other platform + specific issues. Conversely, please add any notes that you know + are important for your platform (or contact one of the doc + maintainers to do this if you can't). + + + + + + + + Source Tarball First, make sure that you have freshly exported the right @@ -2321,7 +2439,7 @@ at sourceforge. Three simple steps: - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup + cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup @@ -2331,8 +2449,8 @@ at sourceforge. Three simple steps: - cd winsetup - make + cd winsetup + make @@ -2345,19 +2463,36 @@ at sourceforge. Three simple steps: Debian - First, make sure that you have freshly exported the right - version into an empty directory. (See "Building and releasing - packages" above). Then, run: - - - - cd current - autoheader && autoconf && ./configure + First, make sure that you have freshly exported the + right version into an empty directory. (See + "Building and releasing packages" above). Then add a log + entry to debian/changelog, if it is not + already there, for example by running: + + + + debchange -v &p-version;-&p-status;-1 "New upstream version" - - - Then do FIXME. - + + + Then, run: + + + + dpkg-buildpackage -rfakeroot -us -uc -b + + + + This will create + ../privoxy_&p-version;-&p-status;-1_i386.deb + which can be uploaded. To upload the package to Sourceforge, simply + issue + + + + make debian-upload + + Mac OSX @@ -2394,7 +2529,7 @@ at sourceforge. Three simple steps: -zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg + zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg @@ -2407,7 +2542,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg FreeBSD - Login to Sourceforge's compilefarm via ssh: + Login to Sourceforge's compile-farm via ssh: @@ -2590,7 +2725,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg Update the Webserver When updating the webserver, please follow these steps to make - sure that no broken links, incosistent contents or permission + sure that no broken links, inconsistent contents or permission problems will occur: @@ -2599,7 +2734,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg - make dok # (or make redkat-dok if make dok doesn't work for you) + make dok # (or make redhat-dok if make dok doesn't work for you) @@ -2700,6 +2835,40 @@ 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.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 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.51 2002/05/29 00:30:59 mal0rd + Fixed a little formatting. Clarified debian section. + + Revision 1.50 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 + -Spellcheck, very minor edits, and sync across branches + + Revision 1.48 2002/05/26 12:48:31 roro + Add releasing information about Debian. + + Revision 1.47 2002/05/26 04:55:11 mal0rd + Added debian-dist and debian-upload targets. Also documented usage. + + Revision 1.46 2002/05/22 17:15:00 oes + Updated intro + + Revision 1.45 2002/05/19 23:01:54 hal9 + Add small section on general packaging guidelines (e.g. actions files must + be writable). + + Revision 1.44 2002/05/15 03:55:17 hal9 + Fix ulink -> link, and minor modification to release process section for + clarification. + Revision 1.43 2002/05/10 01:48:19 hal9 This is mostly proposed copyright/licensing additions and changes. Docs are still GPL, but licensing and copyright are more visible. Also, copyright