X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=89c126426ae735e08c5adc25f6a46fd9bed6e92d;hp=0920b7646c608894f26d675f3006a30cc8ea5c1f;hb=47b73971a4fed5f577628fde3ad12e751b98c53b;hpb=de371cd95abbab8891e7ec3b1981ea9a470da6db
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 0920b764..89c12642 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.43 2002/05/10 01:48:19 hal9 Exp $
+
+
+
@@ -80,10 +96,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 +106,9 @@
-
-
-
-
-
-
-
-
-
- Introduction
+ Introduction
- Quickstart to Privoxy Development
+ Quickstart to Privoxy Development
You'll need an account on Sourceforge to support our
@@ -136,6 +141,7 @@
For the time being (read, this section is under construction), please
refer to the extensive comments in the source code.
+
@@ -389,6 +395,11 @@
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.
+
@@ -1715,7 +1726,7 @@ static void unload_re_filterfile( void *f ) { ... }
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
@@ -1775,7 +1786,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.33 2002/04/12 03:49:53 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
@@ -1947,13 +1958,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.
@@ -1964,24 +2021,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,
@@ -1991,15 +2050,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
@@ -2007,6 +2067,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).
+
+
@@ -2030,7 +2107,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
-
+
@@ -2042,7 +2119,8 @@ 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.
Source Tarball
@@ -2055,7 +2133,7 @@ at sourceforge. Three simple steps:
cd current
autoheader && autoconf && ./configure
-
+
Then do:
@@ -2063,7 +2141,7 @@ at sourceforge. Three simple steps:
make tarball-dist
-
+
To upload the package to Sourceforge, simply issue
@@ -2071,7 +2149,7 @@ at sourceforge. Three simple steps:
make tarball-upload
-
+
Go to the displayed URL and release the file publicly on Sourceforge.
@@ -2080,37 +2158,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.
@@ -2123,7 +2222,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.
@@ -2143,7 +2242,7 @@ at sourceforge. Three simple steps:
installExeName='privoxyos2_setup_X.Y.Z.exe'
-
+
Next, edit the IJB.wis file so the release number matches
@@ -2152,7 +2251,7 @@ at sourceforge. Three simple steps:
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
-
+
You're now ready to build. Run:
@@ -2160,7 +2259,7 @@ at sourceforge. Three simple steps:
os2build
-
+
You will find the WarpIN-installable executable in the
@@ -2178,7 +2277,7 @@ at sourceforge. Three simple steps:
ssh cf.sourceforge.net
-
+
Choose the right operating system (not the Debian one).
@@ -2190,7 +2289,7 @@ at sourceforge. Three simple steps:
cd current
autoheader && autoconf && ./configure
-
+
Then run
@@ -2198,7 +2297,7 @@ at sourceforge. Three simple steps:
gmake solaris-dist
-
+
which creates a gzip'ed tar archive. Sadly, you cannot use make
@@ -2223,7 +2322,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
@@ -2234,7 +2333,7 @@ at sourceforge. Three simple steps:
cd winsetup
make
-
+
Now you can manually rename privoxy_setup.exe to
@@ -2254,7 +2353,7 @@ at sourceforge. Three simple steps:
cd current
autoheader && autoconf && ./configure
-
+
Then do FIXME.
@@ -2270,7 +2369,7 @@ at sourceforge. Three simple steps:
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
-
+
Then run:
@@ -2279,7 +2378,7 @@ at sourceforge. Three simple steps:
cd osxsetup
build
-
+
This will run autoheader, autoconf and
@@ -2296,7 +2395,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
@@ -2313,7 +2412,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
ssh cf.sourceforge.net
-
+
Choose the right operating system.
@@ -2325,7 +2424,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
cd current
autoheader && autoconf && ./configure
-
+
Then run:
@@ -2333,7 +2432,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
@@ -2354,7 +2453,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
cd current
autoheader && autoconf && ./configure
-
+
Then do FIXME.
@@ -2371,7 +2470,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
cd current
autoheader && autoconf && ./configure
-
+
Then do FIXME.
@@ -2385,7 +2484,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
ssh cf.sourceforge.net
-
+
Choose the right operating system.
@@ -2397,7 +2496,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
cd current
autoheader && autoconf && ./configure
-
+
Then run:
@@ -2405,7 +2504,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
@@ -2417,6 +2516,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
@@ -2445,7 +2600,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,
@@ -2471,7 +2626,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
make webserver
-
+
This will do the upload to the
@@ -2491,22 +2646,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
@@ -2537,6 +2700,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.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
+ - 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.