X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=5049edd95b7066b1f506ab2a67097fe93b359246;hb=ec3786121a8db0be59e217dd794d61be9d9dc134;hp=786fdd0b3ba981aba6a7dbb43834732db61d1c63;hpb=0db7d019a0f88288c748ceb1d2d72a6d64d6fdf0;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 786fdd0b..5049edd9 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -1,5 +1,5 @@ + @@ -7,12 +7,14 @@ - + + + ]> + + Copyright &my-copy; 2001, 2002 by + Privoxy Developers + + + + + $Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $ + + + @@ -65,10 +81,11 @@ ]]> - 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. + @@ -80,10 +97,9 @@ You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/. - Please see the Contact section + Please see the Contact section on how to contact the developers. - @@ -91,18 +107,9 @@ - - - - - - - - - - Introduction + Introduction - Quickstart to Privoxy Development + Quickstart to Privoxy Development You'll need an account on Sourceforge to support our @@ -136,6 +142,7 @@ For the time being (read, this section is under construction), please refer to the extensive comments in the source code. + @@ -1720,7 +1727,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.34 2002/04/15 23:39:32 oes Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $"; /********************************************************************* * * File : $Source$ @@ -1780,7 +1787,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.34 2002/04/15 23:39:32 oes Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $" /********************************************************************* * * File : $Source$ @@ -1952,13 +1959,59 @@ at sourceforge. Three simple steps: gmake (GNU's version of make), autoconf, cvs. + + Version numbers + - In the following text, replace X, Y and Z with the actual version number - (X = major, Y = minor, Z = point): + 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: + + + + X, the version major, is rarely ever changed. It is increased by one if + turning a development branch into stable substantially changes the functionality, + user interface or configuration syntax. Majors 1 and 2 were + Junkbuster, and 3 will be the first stable + Privoxy release. + + + + + 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 + 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 + 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. + + + + + Z, the point or sub version, represents a release of the software within a branch. + It is therefore incremented immediately before each code freeze. + In development branches, only the even point versions correspond to actual releases, + while the odd ones denote the evolving state of the sources on CVS in between. + It follows that Z is odd on CVS in development branches most of the time. There, it gets + increased to an even number immediately before a code freeze, and is increased to an odd + number again immediately thereafter. + This ensures that builds from CVS snapshots are easily distinguished from released versions. + The point version is reset to zero when the minor changes. + + + + + - Before the Release + Before the Release: Freeze The following must be done by one of the developers prior to each new release. @@ -1969,24 +2022,26 @@ at sourceforge. Three simple steps: Make sure that everybody who has worked on the code in the last couple of days has had a chance to yell no! in case - they have pending changes/fixes in their pipelines. + they have pending changes/fixes in their pipelines. Announce the + freeze so that nobody will interfere with last minute changes. - Increment the version number and increase or reset the RPM release number - in configure.in as appropriate. + Increment the version number (point from odd to even in development + branches!) in configure.in. - If the default actionsfile has changed since last - release, bump up its version info in this line: + If default.action has changed since last + release (i.e. software release or standalone actions file release), + bump up its version info to A.B in this line: {+add-header{X-Actions-File-Version: A.B} -filter -no-popups} - + Then change the version info in doc/webserver/actions/index.php, @@ -1996,15 +2051,16 @@ at sourceforge. Three simple steps: 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. + 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. Commit all files that were changed in the above steps! - + Tag all files in CVS with the version number with @@ -2012,6 +2068,23 @@ at sourceforge. Three simple steps: Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. + + + If the release was in a development branch, increase the point version + from even to odd (X.Y.(Z+1)) again in configure.in and + commit your change. + + + + + On the webserver, copy the user manual to a new top-level directory + called X.Y.Z. This ensures that help links from the CGI + pages, which have the version as a prefix, will go into the right version of the manual. + If this is a development branch release, also symlink X.Y.(Z-1) + to X.Y.Z and X.Y.(Z+1) to + . (i.e. dot). + + @@ -2035,7 +2108,7 @@ at sourceforge. Three simple steps: 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 - + @@ -2047,9 +2120,110 @@ at sourceforge. Three simple steps: Please find additional instructions for the source tarball and the - individual platform dependent binary packages below. + individual platform dependent binary packages below. And details + 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 (toplevel directory) + + + + + README (toplevel directory) + + + + + AUTHORS (toplevel directory) + + + + + man page (toplevel directory, Unix-like + platforms only) + + + + + The User Manual (doc/webserver/user-manual/) + + + + + FAQ (doc/webserver/faq/) + + + + Also suggested: Developer Manual + (doc/webserver/devel-manual) and ChangeLog + (toplevel 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. index.html can also be included and + can serve as a focal point for docs and other links of interest. + This should be one level up from the manuals. There are two + css stylesheets that can be included for better presentation: + p_doc.css and p_web.css. + These should be in the same directory with + 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 @@ -2060,7 +2234,7 @@ at sourceforge. Three simple steps: cd current autoheader && autoconf && ./configure - + Then do: @@ -2068,7 +2242,7 @@ at sourceforge. Three simple steps: make tarball-dist - + To upload the package to Sourceforge, simply issue @@ -2076,7 +2250,7 @@ at sourceforge. Three simple steps: make tarball-upload - + Go to the displayed URL and release the file publicly on Sourceforge. @@ -2085,37 +2259,58 @@ at sourceforge. Three simple steps: - SuSE or Red Hat + SuSE, Conectiva or Red Hat RPM + + In following text, replace dist + with either rh for Red Hat or suse for SuSE. + First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing - packages" above). Then run: + packages" above). + + + As the only exception to not changing anything after export from CVS, + now examine the file privoxy-dist.spec + and make sure that the version information and the RPM release number are + correct. The RPM release numbers for each version start at one. Hence it must + be reset to one if this is the first RPM for + dist which is built from version + X.Y.Z. Check the + file + list if unsure. Else, it must be set to the highest already available RPM + release number for that version plus one. + + + Then run: cd current autoheader && autoconf && ./configure - + Then do - make suse-dist (or make redhat-dist) - + make dist-dist + To upload the package to Sourceforge, simply issue - make suse-upload (or make redhat-upload) - + make dist-upload rpm_packagerev + + where rpm_packagerev is the + RPM release number as determined above. Go to the displayed URL and release the file publicly on Sourceforge. - Use the release notes and çhange log from the source tarball package. + Use the release notes and change log from the source tarball package. @@ -2128,7 +2323,7 @@ at sourceforge. Three simple steps: cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup - + You will need a mix of development tools. @@ -2148,7 +2343,7 @@ at sourceforge. Three simple steps: installExeName='privoxyos2_setup_X.Y.Z.exe' - + Next, edit the IJB.wis file so the release number matches @@ -2157,7 +2352,7 @@ at sourceforge. Three simple steps: PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z" - + You're now ready to build. Run: @@ -2165,7 +2360,7 @@ at sourceforge. Three simple steps: os2build - + You will find the WarpIN-installable executable in the @@ -2183,7 +2378,7 @@ at sourceforge. Three simple steps: ssh cf.sourceforge.net - + Choose the right operating system (not the Debian one). @@ -2195,7 +2390,7 @@ at sourceforge. Three simple steps: cd current autoheader && autoconf && ./configure - + Then run @@ -2203,7 +2398,7 @@ at sourceforge. Three simple steps: gmake solaris-dist - + which creates a gzip'ed tar archive. Sadly, you cannot use make @@ -2228,7 +2423,7 @@ at sourceforge. Three simple steps: cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup - + Then you can build the package. This is fully automated, and is @@ -2239,7 +2434,7 @@ at sourceforge. Three simple steps: cd winsetup make - + Now you can manually rename privoxy_setup.exe to @@ -2259,7 +2454,7 @@ at sourceforge. Three simple steps: cd current autoheader && autoconf && ./configure - + Then do FIXME. @@ -2275,7 +2470,7 @@ at sourceforge. Three simple steps: cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup - + Then run: @@ -2284,7 +2479,7 @@ at sourceforge. Three simple steps: cd osxsetup build - + This will run autoheader, autoconf and @@ -2301,7 +2496,7 @@ at sourceforge. Three simple steps: zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg - + You can then upload privoxyosx_setup_x.y.z.zip anonymously to @@ -2318,7 +2513,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg ssh cf.sourceforge.net - + Choose the right operating system. @@ -2330,7 +2525,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg cd current autoheader && autoconf && ./configure - + Then run: @@ -2338,7 +2533,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg gmake freebsd-dist - + which creates a gzip'ed tar archive. Sadly, you cannot use make @@ -2359,7 +2554,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg cd current autoheader && autoconf && ./configure - + Then do FIXME. @@ -2376,7 +2571,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg cd current autoheader && autoconf && ./configure - + Then do FIXME. @@ -2390,7 +2585,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg ssh cf.sourceforge.net - + Choose the right operating system. @@ -2402,7 +2597,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg cd current autoheader && autoconf && ./configure - + Then run: @@ -2410,7 +2605,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg make aix-dist - + which creates a gzip'ed tar archive. Sadly, you cannot use make @@ -2422,6 +2617,62 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg + + Uploading and Releasing Your Package + + After the package is ready, it is time to upload it + to SourceForge, and go through the release steps. The upload + is done via FTP: + + + + + + Upload to: ftp://upload.sourceforge.net/incoming + + + + + user: anonymous + + + + + password: ijbswa-developers@lists.sourceforge.net + + + + + + Or use the make targets as described above. + + + Once this done go to http://sourceforge.net/project/admin/editpackages.php?group_id=11118, + making sure you are logged in. Find your target platform in the + second column, and click Add Release. You will + then need to create a new release for your package, using the format + of $VERSION ($CODE_STATUS), e.g. &p-version; + (beta). + + + Now just follow the prompts. Be sure to add any appropriate Release + notes. You should see your freshly uploaded packages in + Step 2. Add Files To This Release. Check the + appropriate box(es). Remember at each step to hit the + Refresh/Submit buttons! You should now see your + file(s) listed in Step 3. Fill out the forms with the appropriate + information for your platform, being sure to hit Update + for each file. If anyone is monitoring your platform, check the + email box at the very bottom to notify them of + the new package. This should do it! + + + If you have made errors, or need to make changes, you can go through + essentially the same steps, but select Edit Release, + instead of Add Release. + + + After the Release @@ -2450,7 +2701,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) - + That will generate doc/webserver/user-manual, @@ -2476,7 +2727,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg make webserver - + This will do the upload to the @@ -2496,22 +2747,30 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg - - Copyright and History -Copyright + +Privoxy Copyright, License and History + ©right; + + +License + + &license; + + + History &history; - + See also @@ -2542,6 +2801,44 @@ 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.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 + changed in doc header comments (eliminate references to JB except FAQ). + + Revision 1.42 2002/05/05 20:26:02 hal9 + Sorting out license vs copyright in these docs. + + Revision 1.41 2002/05/04 08:44:44 swa + bumped version + + Revision 1.40 2002/05/04 00:43:43 hal9 + -Remove TOC/first page kludge with proper stylesheet fix. + -Combined the two very brief sections: Intro and Quickstart. + + Revision 1.39 2002/05/02 15:08:25 oes + Added explanation about version numbers and RPM package revisions + + Revision 1.38 2002/04/29 02:20:31 hal9 + Add info on steps for uploading and the release process on SF. + + Revision 1.37 2002/04/26 17:23:29 swa + bookmarks cleaned, changed structure of user manual, screen and programlisting cleanups, and numerous other changes that I forgot + + Revision 1.36 2002/04/26 05:25:23 hal9 + Mass commit to catch a few scattered fixes. + + Revision 1.35 2002/04/17 15:16:15 oes + Added link to docbook crash course + Revision 1.34 2002/04/15 23:39:32 oes - Extended & fixed the release section - Added CVS guideline sections