X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=60ca51b9e3c0e84273d425714a70f231a06d8c56;hp=8b36ac4351d21810bd9edd87e6d2d7478e9bedcc;hb=ee0ab00a07f0abda120329e593e5587640960e57;hpb=e70110618027c7cb90164df41ae9b5fefb6ef5ac diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 8b36ac43..60ca51b9 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,10 +8,10 @@ - - + + - + @@ -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.20 2008/06/14 13:21:24 fabiankeil Exp $ - Copyright (C) 2001, 2002 Privoxy Developers + Copyright (C) 2001-2008 Privoxy Developers http://www.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 - Privoxy Developers + Copyright &my-copy; 2001-2008 by + Privoxy Developers - $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 fabiankeil Exp $ - + @@ -82,7 +84,8 @@ Hal. 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. + for anyone who wants to join the team. Note that it's currently out of date + and may not be entirely correct. As always, patches are welcome. @@ -93,6 +96,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 @@ -115,20 +120,22 @@ Hal. --> Privoxy, as an heir to - Junkbuster, is an Open Source project - and licensed under the GPL. As such, Privoxy - development is potentially open to anyone who has the time, knowledge, - and desire to contribute in any capacity. Our goals are simply to - continue the mission, to improve Privoxy, and + Junkbuster, is a Free Software project + and the code is licensed under the GNU General Public License version 2. + As such, Privoxy development is potentially open + to anyone who has the time, knowledge, and desire to contribute + in any capacity. Our goals are simply to continue the mission, + to improve Privoxy, and to make it available to as wide an audience as possible. One does not have to be a programmer to contribute. Packaging, testing, - and porting, are all important jobs as well. + documenting and porting, are all important jobs as well. 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. + + + 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), please - refer to the extensive comments in the source code. + 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 +168,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 +182,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 +268,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 +340,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 +349,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 +362,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 +394,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 +505,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 +593,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: @@ -639,8 +733,8 @@ Hal. Explanation: Comment as much as possible without commenting the obvious. - For example do not comment "aVariable is equal to bVariable". - Instead explain why aVariable should be equal to the bVariable. + For example do not comment "variable_a is equal to variable_b". + Instead explain why variable_a should be equal to the variable_b. Just because a person can read code does not mean they will understand why or what is being done. A reader may spend a lot more time figuring out what is going on when a simple comment @@ -654,13 +748,13 @@ Hal. Example: /* if page size greater than 1k ... */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } /* if page size is small, send it in blocks */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } @@ -688,22 +782,22 @@ is actually being done. /********************************************************************* * This will stand out clearly in your code! *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } /* unfortunately, this may not */ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /* this may not either */ +if ( this_variable == that_variable ) /* this may not either */ { - DoSomethingVeryImportant(); + do_something_very_important(); } Exception: @@ -735,14 +829,14 @@ if ( thisVariable == thatVariable ) /* this may not either */ * This will stand out clearly in your code, * But the second example won't. *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /*can you see me?*/ +if ( this_variable == this_variable ) /*can you see me?*/ { - DoSomethingVeryImportant(); /*not easily*/ + do_something_very_important(); /*not easily*/ } @@ -754,17 +848,17 @@ int urls_rejected = 0; /* # of urls rejected */ if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -short DoSomethingVeryImportant( +short do_something_very_important( short firstparam, /* represents something */ short nextparam /* represents something else */ ) { ...code here... -} /* -END- DoSomethingVeryImportant */ +} /* -END- do_something_very_important */ @@ -831,7 +925,7 @@ short DoSomethingVeryImportant( if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ @@ -839,7 +933,7 @@ or: if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if ( 1 == X ) */ @@ -1056,17 +1150,17 @@ while ( more lines are read ) if ( this == that ) { - DoSomething(); - DoSomethingElse(); + do_something(); + do_something_else(); } Instead of: - if ( this == that ) DoSomething(); DoSomethingElse(); + if ( this == that ) do_something(); do_something_else(); or - if ( this == that ) DoSomething(); + if ( this == that ) do_something(); Note: The first example in "Instead of" will execute in a manner other than that which the developer desired (per @@ -1109,14 +1203,14 @@ structure->flag = ( condition ); Example: -int firstValue = 0; -int someValue = 0; -int anotherValue = 0; -int thisVariable = 0; +int first_value = 0; +int some_value = 0; +int another_value = 0; +int this_variable = 0; -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) -firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) +first_value = old_value + ( ( some_value - another_value ) - whatever ) @@ -1136,12 +1230,12 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) Example: -aStruct->aMember; -aStruct.aMember; -FunctionName(); +a_struct->a_member; +a_struct.a_member; +function_name(); - Instead of: aStruct -> aMember; aStruct . aMember; - FunctionName (); + Instead of: a_struct -> a_member; a_struct . a_member; + function_name (); @@ -1155,7 +1249,7 @@ FunctionName(); int function1( ... ) { ...code... - return( retCode ); + return( ret_code ); } /* -END- function1 */ @@ -1167,7 +1261,7 @@ int function2( ... ) Instead of: - int function1( ... ) { ...code... return( retCode ); } int + int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) { } Note: Use 1 blank line before the closing brace and 2 @@ -1237,14 +1331,14 @@ int function1( ... ) Example: -short anShort = 0; -float aFloat = 0; +short a_short = 0; +float a_float = 0; struct *ptr = NULL; Note: It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 - and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. - arrayPtr[0]. + and not 129FA012; or array_ptr[20] causes a SIGSEV vs. + array_ptr[0]. Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. @@ -1267,9 +1361,9 @@ struct *ptr = NULL; Example: -ShouldWeBlockThis(); -ContainsAnImage(); -IsWebPageBlank(); +should_we_block_this(); +contains_an_image(); +is_web_page_blank(); @@ -1298,7 +1392,7 @@ IsWebPageBlank(); Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) { .... } @@ -1307,10 +1401,10 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) each and every iteration. This increases the overhead in the program, because the compiler has to look up the function each time, call it, and return a value. Depending on what occurs in - the blockListLength() call, it might even be creating and + the block_list_length() call, it might even be creating and destroying structures with each iteration, even though in each case it is comparing "cnt" to the same value, over and over. - Remember too - even a call to blockListLength() is a function + Remember too - even a call to block_list_length() is a function call, with the same overhead. Instead of using a function call during the iterations, @@ -1319,15 +1413,15 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) Example: -size_t len = blockListLength(); +size_t len = block_list_length(); -for ( size_t cnt = 0; cnt < len; cnt ++ ) +for ( size_t cnt = 0; cnt < len; cnt++ ) { .... } - Exceptions: if the value of blockListLength() *may* - change or could *potentially* change, then you must code the + Exceptions: if the value of block_list_length() + *may* change or could *potentially* change, then you must code the function call in the for/while loop. @@ -1533,7 +1627,7 @@ switch( hash_string( cmd ) ) Another Note: This is not so much a readability issue 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. + load_config). Or it may really be an abort condition. Status: Programmer discretion is advised. @@ -1592,8 +1686,7 @@ switch( hash_string( cmd ) ) assumptions about whether it is signed or unsigned, or about how long it is. Do not compare a size_t against another variable of a different type (or even against a constant) - without casting one of the values. Try to avoid using size_t if - you can. + without casting one of the values. @@ -1625,7 +1718,7 @@ long c = 0; Exceptions: when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them - on 1 line. You should, although, provide a good comment on + on one line. You should, although, provide a good comment on their functions. Status: developer-discretion. @@ -1703,7 +1796,7 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to - existing code, use FIXME + existing code, use FIXME or XXX Explanation: @@ -1740,14 +1833,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.20 2008/06/14 13:21:24 fabiankeil 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-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1769,8 +1862,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 +1894,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.20 2008/06/14 13:21:24 fabiankeil 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-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1829,8 +1923,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 +2073,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 +2112,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 +2171,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 +2193,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 +2267,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 +2287,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 +2382,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 +2409,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 +2522,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 +2622,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 @@ -2495,15 +2678,15 @@ at sourceforge. Three simple steps: - Mac OSX + Mac OS X 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: + packages" above). Then get the Mac OS X setup module: - 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 @@ -2681,7 +2864,9 @@ at sourceforge. Three simple steps: Or use the make targets as described above. - Once this done go to http://sourceforge.net/project/admin/editpackages.php?group_id=11118, + Once this done go to https://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 @@ -2715,7 +2900,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 +2912,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 +2946,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 +2961,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 +3028,89 @@ 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.20 2008/06/14 13:21:24 fabiankeil + Prepare for the upcoming 3.0.9 beta release. + + Revision 2.19 2008/05/12 11:13:33 fabiankeil + Clarify that Privoxy is licensed under GPL version 2. + + Revision 2.18 2008/02/04 12:14:06 fabiankeil + Change "Edit Packages" URL to use https. + + Revision 2.17 2008/02/03 21:37:41 hal9 + Apply patch from Mark: s/OSX/OS X/ + + Revision 2.16 2008/01/19 17:52:38 hal9 + Re-commit to fix various minor issues for new release. + + Revision 2.15 2008/01/19 15:03:05 hal9 + Doc sources tagged for 3.0.8 release. + + Revision 2.14 2008/01/17 01:49:51 hal9 + Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon + enough. + + Revision 2.13 2007/10/30 17:59:31 fabiankeil + - Bump p-version, p-status and copyright date. + - Mention that the manual is out of date. + - Don't use examples with HardToReadCamelCase after + explaining that we actually don't like that. + - Minor cosmetics. + + Revision 2.12 2006/11/14 01:57:46 hal9 + Dump all docs prior to 3.0.6 release. Various minor changes to faq and user + manual. + + Revision 2.11 2006/09/26 02:36:29 hal9 + Fix broken link per bug tracker. + + 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 @@ -2955,7 +3216,7 @@ at sourceforge. Three simple steps: More boilerplate text for use across multiple docs. Revision 1.20 2002/04/04 03:28:27 david__schmidt - Add Mac OSX section + Add Mac OS X section Revision 1.19 2002/04/03 15:09:42 david__schmidt Add OS/2 build section