X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=89c126426ae735e08c5adc25f6a46fd9bed6e92d;hp=8a5af0cef960a1ef3abc71335544f3bdaa0b653c;hb=47b73971a4fed5f577628fde3ad12e751b98c53b;hpb=5ff5afa53bc3b5860b40ce780223b59acfa01205
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 8a5af0ce..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 $
+
+
+
@@ -72,16 +88,17 @@
- &p-intro;
+
You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/.
- Please see the Contact section on how to contact the developers.
+ Please see the Contact section
+ on how to contact the developers.
-
@@ -89,18 +106,9 @@
-
-
-
-
-
-
-
-
-
- Introduction
+ Introduction
+ Quickstart to Privoxy Development
+
+ You'll need an account on Sourceforge to support our
+ development. Mail your ID to the list and wait until a
+ project manager has added you.
+
+
+ For the time being (read, this section is under construction), please
+ refer to the extensive comments in the source code.
+
+
- Quickstart to Privoxy Development
+ The CVS Repository
-You'll need an account on Sourceforge to support our development.
-Mail your ID to the list and wait until a project manager has added you.
-
+ 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.
+
-
-For the time being (read, this section is under construction), please note the
-following guidelines for changing stuff in the code. If it is
-
-
- A bugfix / clean-up / cosmetic thing: shoot
-
-
- A new feature that can be turned off: shoot
-
-
- A clear improvement w/o side effects on other parts of the code: shoot
-
-
- A matter of taste: ask the list
-
-
- A major redesign of some part of the code: ask the list
-
-
-
-
+ Access to CVS
+
+ The project's CVS repository is hosted on
+ SourceForge.
+ Please refer to the chapters 6 and 7 in
+ 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, and the source tree module is called
+ current.
+
+
+
+ CVS Commit Guideline
+
+ 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:
+
+
+ Never (read: never, ever) be tempted to commit
+ that small change without testing it thoroughly first. When we're
+ close to a public release, ask a fellow developer to review your
+ changes.
+
+
+ Your commit message should give a concise overview of what you
+ changed (no big details) and why you changed it
+ Just check previous messages for good examples.
+
+
+ Don't use the same message on multiple files, unless it equally applies to
+ all those files.
+
+
+ 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.
+ If necessary, prepare the commit messages in advance.
+
+
+ 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).
+
+
+
+
+
+ Discussing Changes First
+
+ 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 new feature that can be turned off: shoot
+
+
+ ..a clear improvement w/o side effects on other parts of the code: shoot
+
+
+ ..a matter of taste: ask the list
+
+
+ ..a major redesign of some part of the code: ask
+ the list
+
+
+
+
+ Note that near a major public release, we get a bit more cautious - if
+ unsure, it doesn't hurt to ask first. There is always the possibility
+ to submit a patch to the patches
+ tracker instead.
+
+
+
Documentation Guidelines
- All formal documents are maintained in docbook SGML and located in the
+ All formal documents are maintained in Docbook SGML and located in the
doc/source/* directory. You will need
Docbook, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
@@ -177,7 +259,7 @@ following guidelines for changing stuff in the code. If it is
Other, less formal documents (e.g. LICENSE,
INSTALL) are maintained as plain text files in the
- toplevel source directory. At least for the time being.
+ top-level source directory. At least for the time being.
Packagers are encouraged to include this documentation. For those without
@@ -196,7 +278,7 @@ following guidelines for changing stuff in the code. If it is
Documentation writers should please make sure documents build
- successfully before committing to CVS.
+ successfully before committing to CVS, if possible.
How do you update the webserver (i.e. the pages on privoxy.org)?
@@ -215,6 +297,15 @@ following guidelines for changing stuff in the code. If it is
+
+ Finished docs should be occasionally submitted to CVS
+ (doc/webserver/*/*.html) so that those without
+ the ability to build them locally, have access to them if needed.
+ This is especially important just prior to a new release! Please
+ do this after the $VERSION and
+ other release specific data in configure.in has been
+ updated (this is done just prior to a new release).
+
@@ -260,51 +351,57 @@ following guidelines for changing stuff in the code. If it is
Some common elements that you likely will use:
-
-
- <para></para>, paragraph delimiter. Most
- text needs to be within paragraph elements (there are some exceptions).
-
-
- <emphasis></emphasis>, the stylesheets make this
- italics.
-
-
- <filename></filename>, files and directories.
-
-
- <command></command>, command examples.
-
-
- <literallayout></literllayout>, like
- <pre>, more or less.
-
-
- <itemizedlist></itemizdelist>, list with bullets.
-
-
- <listitem></listitem>, member of the above.
-
-
- <screen></screen>, screen output, implies
- <literallayout>.
-
-
- <ulink url="example.com"></ulink>, like
- HTML <a> tag.
-
-
- <quote></quote>, for, doh, quoting text.
-
-
+
+
+
+ <para></para>, paragraph delimiter. Most
+ text needs to be within paragraph elements (there are some exceptions).
+
+
+ <emphasis></emphasis>, the stylesheets
+ make this italics.
+
+
+ <filename></filename>, files and directories.
+
+
+ <command></command>, command examples.
+
+
+ <literallayout></literallayout>, like
+ <pre>, more or less.
+
+
+ <itemizedlist></itemizedlist>, list with bullets.
+
+
+ <listitem></listitem>, member of the above.
+
+
+ <screen></screen>, screen output, implies
+ <literallayout>.
+
+
+ <ulink url="example.com"></ulink>, like
+ HTML <a> tag.
+
+
+ <quote></quote>, for, doh, quoting text.
+
+
+
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.
+
-
<application>Privoxy</application> Documentation Style
@@ -374,13 +471,14 @@ following guidelines for changing stuff in the code. If it is
We have an international audience. Refrain from slang, or English
- idiosyncrasies (too many to list :).
+ idiosyncrasies (too many to list :). Humor also does not translate
+ well sometimes.
Try to keep overall line lengths in source files to 80 characters or less
- for obvious reasons. This is not always possible, with lenghty URLs for
+ for obvious reasons. This is not always possible, with lengthy URLs for
instance.
@@ -448,7 +546,7 @@ following guidelines for changing stuff in the code. If it is
- Re-cyclable boilerplate
text entities are defined like:
+ Re- boilerplate
text entities are defined like:
<!entity supported SYSTEM "supported.sgml">
@@ -469,15 +567,15 @@ following guidelines for changing stuff in the code. If it is
p-version: the Privoxy
- version string, e.g. 2.9.13
.
+ version string, e.g. &p-version;
.
p-status: the project status, either
- ALPHA
, BETA
, or STABLE
.
+ alpha
, beta
, or stable
.
p-not-stable: use to conditionally include
- text in not stable
releases (e.g. BETA
).
+ text in not stable
releases (e.g. beta
).
p-stable: just the opposite.
@@ -597,7 +695,7 @@ if ( thisVariable == thatVariable ) /* this may not either */
Exception:
If you are trying to add a small logic comment and do not
- wish to "disrubt" the flow of the code, feel free to use a 1
+ wish to "disrupt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.
@@ -743,7 +841,7 @@ if ( 1 == X )
Explanation:
- Use all lowercase, and seperate words via an underscore
+ Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
@@ -770,7 +868,7 @@ int msiis5hack = 0; int msIis5Hack = 0;
Explanation:
- Use all lowercase, and seperate words via an underscore
+ Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
@@ -912,11 +1010,11 @@ if ( this == that )
Note: In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
- condidtion that is obvious from the purpose of the block,
+ condition that is obvious from the purpose of the block,
one-liners as above may optically preserve the loop structure
and make it easier to read.
- Status: developer-discrection.
+ Status: developer-discretion.
Example exception:
@@ -978,7 +1076,7 @@ structure->flag = ( condition );
if ( condition ) { structure->flag = 1; } else {
structure->flag = 0; }
- Note: The former is readable and consice. The later
+ Note: The former is readable and concise. The later
is wordy and inefficient. Please assume that any developer new
to the project has at least a "good" knowledge of C/C++. (Hope
I do not offend by that last comment ... 8-)
@@ -1059,14 +1157,14 @@ int function2( ... )
function2( ... ) { }
Note: Use 1 blank line before the closing brace and 2
- lines afterwards. This makes the end of function standout to
+ lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
- seperate functions, this is still a good coding practice. In
+ separate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!
- Status: developer-discrection on the number of blank
+ Status: developer-discretion on the number of blank
lines. Enforced is the end of function comments.
@@ -1134,7 +1232,7 @@ struct *ptr = NULL;
and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
arrayPtr[0].
- Status: developer-discrection if and only if the
+ Status: developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.
@@ -1287,7 +1385,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ )
Note: Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.
+ "file.h" behavior.
@@ -1360,9 +1458,9 @@ extern file_list *xyz;
Note: If you declare "file_list xyz;" (without the
pointer), then including the proper header file is necessary.
If you only want to prototype a pointer, however, the header
- file is unneccessary.
+ file is unnecessary.
- Status: Use with discrection.
+ Status: Use with discretion.
@@ -1408,7 +1506,7 @@ switch( hash_string( cmd ) )
default :
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */
@@ -1419,7 +1517,7 @@ switch( hash_string( cmd ) )
This API call *should* be included in a default statement.
Another Note: This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
+ 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.
@@ -1516,7 +1614,7 @@ long c = 0;
on 1 line. You should, although, provide a good comment on
their functions.
- Status: developer-discrection.
+ Status: developer-discretion.
@@ -1526,7 +1624,7 @@ long c = 0;
Explanation:
- Create a local stuct (on the stack) if the variable will
+ Create a local struct (on the stack) if the variable will
live and die within the context of one function call.
Only "malloc" a struct (on the heap) if the variable's life
@@ -1535,7 +1633,7 @@ long c = 0;
Example:
If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.
+list, then it should definitely be allocated via `malloc'.
@@ -1551,7 +1649,7 @@ list, then it should definately 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 accomodate this.
+ free/unload/destuctor type function to accommodate this.
Example:
@@ -1564,7 +1662,7 @@ static void unload_re_filterfile( void *f ) { ... }
functions for C run-time library functions ... such as
`strdup'.
- Status: developer-discrection. The "main" use of this
+ Status: developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).
@@ -1591,16 +1689,16 @@ static void unload_re_filterfile( void *f ) { ... }
"Uncertain" new code and/or changes to
- exitinst code, use FIXME
+ existing code, use FIXME
Explanation:
If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
+ your changes, but are not *quite* sure of the repercussions,
add this:
/* FIXME: this code has a logic error on platform XYZ, *
- attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif
or:
@@ -1615,7 +1713,7 @@ static void unload_re_filterfile( void *f ) { ... }
Note: If you make it clear that this may or may not
be a "good thing (tm)", it will be easier to identify and
- include in the project (or conversly exclude from the
+ include in the project (or conversely exclude from the
project).
@@ -1628,7 +1726,7 @@ static void unload_re_filterfile( void *f ) { ... }
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
@@ -1680,7 +1778,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
Note: The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
- skip the verbige and get to the heart of the code (via
+ skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.
@@ -1688,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.27 2002/04/08 15:31:18 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.43 2002/05/10 01:48:19 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
@@ -1784,13 +1882,6 @@ int FUNCTION_NAME( void *param1, const char *x )
-
- Version Control Guidelines
- To be filled. note on cvs comments. Don't only comment what you did,
- but also why you did it!
-
-
-
Testing Guidelines
To be filled.
@@ -1847,24 +1938,82 @@ at sourceforge. Three simple steps:
- Releasing a new version
+ Releasing a New Version
+
+ When we release versions of Privoxy,
+ our work leaves our cozy secret lab and has to work in the cold
+ RealWorld[tm]. Once it is released, there is no way to call it
+ back, so it is very important that great care is taken to ensure
+ that everything runs fine, and not to introduce problems in the
+ very last minute.
+
- To minimize trouble with distribution contents, webpage
- errors and the like, we strongly encourage you
- to follow this section if you prepare a new release of
- code or new pages on the webserver.
+ So when releasing a new version, please adhere exactly to the
+ procedure outlined in this chapter.
+
The following programs are required to follow this process:
- ncftpput (ncftp), scp (ssh),
-gmake (GNU's version of make), autoconf, cvs, ???.
+ ncftpput (ncftp), scp, ssh (ssh),
+ gmake (GNU's version of make), autoconf, cvs.
+
+
+ Version numbers
+
+
+ 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:
+ developers prior to each new release.
@@ -1872,136 +2021,208 @@ 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 in configure.in in
- CVS. Also, the RPM release number in
- configure.in. Do NOT touch version information
- after export from CVS. All packages will use the
- version and release data from configure.in.
- Local files should not be changed, except prior to a CVS commit!!!
- This way we are all on the same page!
+ 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,
line: '$required_actions_file_version = "A.B";'
+
+
+
+ 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.
+
+
+
+ Commit all files that were changed in the above steps!
+
+
Tag all files in CVS with the version number with
- cvs tag v_X_Y_Z
(where X = major, Y
- = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
- etc.
+ cvs tag v_X_Y_Z
.
+ Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
-
+
- The first package uploaded should be the official
- tarball
release. This is built with the
- make tarball-dist
Makefile
- target, and then can be uploaded with
- make tarball-upload
(see below).
+ 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).
- Update the webserver
-
- All files must be group-readable and group-writable (or no one else
- will be able to change them). To update the webserver, create any
- pages locally in the doc/webserver directory (or
- create new directories under doc/webserver), then do
+
+ Building and Releasing the Packages
+
+ Now the individual packages can be built and released. Note that for
+ GPL reasons the first package to be released is always the source tarball.
+
+
+
+ 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:.
+
+
+
+
+ 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
+
+
+
+
+ Do NOT change a single bit, including, but not limited to
+ version information after export from CVS. This is to make sure that
+ all release packages, and with them, all future bug reports, are based
+ on exactly the same code.
+
+
+
+ Please find additional instructions for the source tarball and the
+ individual platform dependent binary packages below. And details
+ on the Sourceforge release process below that.
+
+
+ Source Tarball
+
+ First, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then run:
-
- make webserver
-
+
+ cd current
+ autoheader && autoconf && ./configure
+
- Note that make dok
- (or make redhat-dok
) creates
- doc/webserver/user-manual,
- doc/webserver/developer-manual,
- doc/webserver/faq and
- doc/webserver/man-page automatically.
-
-
- Please do NOT use any other means of transferring files to the
- webserver. make webserver
not only
- uploads, but will make sure that the appropriate permissions are
- preserved for shared group access.
+ Then do:
+
+
+
+ make tarball-dist
+
+
+
+ To upload the package to Sourceforge, simply issue
+
+
+
+ make tarball-upload
+
+
+
+ Go to the displayed URL and release the file publicly on Sourceforge.
+ For the change log field, use the relevant section of the
+ ChangeLog file.
-
+
- SuSE or Red Hat
-
- Ensure that you have the latest code version. Hence run:
+ 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).
-
- cd current
- 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
-
+ 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.
- first.
+ 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 change log from the source tarball package.
-
+
- OS/2
+ OS/2
- Ensure that you have the latest code version. Hence run:
+ First, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then get the OS/2 Setup module:
- cd current
- 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
- cd ..
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
-
+
You will need a mix of development tools.
@@ -2017,55 +2238,58 @@ at sourceforge. Three simple steps:
Change directory to the os2setup directory.
Edit the os2build.cmd file to set the final executable filename.
For example,
+
+
installExeName='privoxyos2_setup_X.Y.Z.exe'
-
+
+
+
Next, edit the IJB.wis file so the release number matches
in the PACKAGEID section:
-
+
+
+
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
-
+
+
+
You're now ready to build. Run:
+
+
os2build
-
- And in the ./files directory you will have the
- WarpIN-installable executable.
- Upload this anonymously to
- uploads.sourceforge.net/incoming, create a release
- for it, and you're done.
+
-
+
+ You will find the WarpIN-installable executable in the
+ ./files directory. Upload this anonymously to
+ uploads.sourceforge.net/incoming, create a release
+ for it, and you're done. Use the release notes and Change Log from the
+ source tarball package.
+
+
- Solaris
+ Solaris
- Login to Sourceforge's compilefarm via ssh
+ Login to Sourceforge's compilefarm via ssh:
ssh cf.sourceforge.net
-
+
- Choose the right operating system (not the Debian one). If you have
- downloaded Privoxy before,
+ Choose the right operating system (not the Debian one).
+ When logged in, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then run:
cd current
- 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
-
-
-
- If not, please checkout
- Privoxy via CVS first. Run:
-
-
-
autoheader && autoconf && ./configure
-
+
Then run
@@ -2073,82 +2297,88 @@ at sourceforge. Three simple steps:
gmake solaris-dist
-
+
which creates a gzip'ed tar archive. Sadly, you cannot use make
solaris-upload on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
-
+
- Windows
+ Windows
- Ensure that you have the latest code version. Hence run
-
-
-
- cd current
- 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
-
-
-
- Run:
-
-
-
- autoheader && autoconf && ./configure
-
-
-
- Then do FIXME.
-
-
+ You should ensure you have the latest version of Cygwin (from
+ http://www.cygwin.com/).
+ Run the following commands from within a Cygwin bash shell.
+
+
+ First, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then get the Windows setup module:
+
+
+
+ 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
+ controlled by winsetup/GNUmakefile.
+ All you need to do is:
+
+
+
+ cd winsetup
+ make
+
+
+
+ Now you can manually rename privoxy_setup.exe to
+ privoxy_setup_X_Y_Z.exe, and upload it to
+ SourceForge. When releasing the package on SourceForge, use the release notes
+ and Change Log from the source tarball package.
+
+
- Debian
+ Debian
- Ensure that you have the latest code version. Hence run:
+ 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
- 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
-
-
-
- first. Run:
-
-
-
autoheader && autoconf && ./configure
-
+
Then do FIXME.
-
+
- Mac OSX
+ Mac OSX
- Ensure that you have the latest code version. Hence run:
+ 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:
- cd current
- 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
- cd ..
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
-
+
+
+
+ Then run:
- From the osxsetup directory, run:
+ cd osxsetup
build
-
+
This will run autoheader, autoconf and
@@ -2161,52 +2391,40 @@ at sourceforge. Three simple steps:
name to match the release, and hit the "Create package" button.
If you specify ./Privoxy.pkg as the output package name, you can then create
the distributable zip file with the command:
+
+
zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
-
+
+
+
You can then upload privoxyosx_setup_x.y.z.zip anonymously to
uploads.sourceforge.net/incoming,
- create a release for it, and you're done.
+ create a release for it, and you're done. Use the release notes
+ and Change Log from the source tarball package.
-
+
- FreeBSD
-
- Change the version number of Privoxy in the
- configure.in file. Run:
-
- autoheader && autoconf && ./configure
-
- Then ...
-
+ FreeBSD
Login to Sourceforge's compilefarm via ssh:
ssh cf.sourceforge.net
-
+
- Choose the right operating system. If you have downloaded Privoxy
- before,
+ Choose the right operating system.
+ When logged in, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then run:
cd current
- 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
-
-
-
- If not, please checkout
- Privoxy via CVS first. Run:
-
-
-
autoheader && autoconf && ./configure
-
+
Then run:
@@ -2214,134 +2432,71 @@ 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
freebsd-upload on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
-
+
- Tarball
+ HP-UX 11
- Ensure that you have the latest code version. Hence run:
+ 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
- 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
-
-
-
- first. Run:
-
-
-
- make clobber
autoheader && autoconf && ./configure
-
-
-
- Then do:
-
-
-
- make tarball-dist
-
-
-
- To upload the package to Sourceforge, simply issue
-
-
-
- make tarball-upload
-
-
-
- Goto the displayed URL and release the file publicly on Sourceforge.
-
-
-
- HP-UX 11
-
- Ensure that you have the latest code version. Hence run:
-
-
-
- cd current
- 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
-
-
-
- first. Run:
-
-
-
- autoheader && autoconf && ./configure
-
+
Then do FIXME.
-
+
- Amiga OS
+ Amiga OS
- Ensure that you have the latest code version. Hence run:
+ 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
- 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
-
-
-
- first. Run:
-
-
-
autoheader && autoconf && ./configure
-
+
Then do FIXME.
-
+
- AIX
+ AIX
Login to Sourceforge's compilefarm via ssh:
ssh cf.sourceforge.net
-
+
- Choose the right operating system. If you have downloaded Privoxy
- before:
+ Choose the right operating system.
+ When logged in, make sure that you have freshly exported the right
+ version into an empty directory. (See "Building and releasing
+ packages" above). Then run:
cd current
- 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
-
-
-
- If not, please checkout
- Privoxy via CVS first. Run:
-
-
-
autoheader && autoconf && ./configure
-
+
Then run:
@@ -2349,18 +2504,141 @@ 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
aix-upload on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly.
+ the file publicly. Use the release notes and Change Log from the
+ source tarball package.
-
+
+
+
+
+ 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
+
+ When all (or: most of the) packages have been uploaded and made available,
+ send an email to the announce
+ mailing list, Subject: "Version X.Y.Z available for download". Be sure to
+ include the
+ download
+ location, the release notes and the change log.
+
+
+
+ Update the Webserver
+
+ When updating the webserver, please follow these steps to make
+ sure that no broken links, incosistent contents or permission
+ problems will occur:
+
+
+ If you have changed anything in the documentation source SGML files,
+ do:
+
+
+
+ make dok # (or make redkat-dok 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/index.html automatically.
+
+
+ If you changed the manual page source, 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.)
+
+
+ If you want to add new files to the webserver, create them locally in
+ the doc/webserver/* directory (or
+ create new directories under doc/webserver).
+
+
+ Next, commit any changes from the above steps to CVS. All set? Then do
+
+
+
+ make webserver
+
+
+
+ This will do the upload to the
+ webserver (www.privoxy.org) and ensure all files and directories
+ there are group writable.
+
+
+ Please do NOT use any other means of transferring
+ files to the webserver to avoid permission problems.
+
+
+
Contacting the developers, Bug Reporting and Feature Requests
@@ -2368,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
@@ -2414,6 +2700,62 @@ 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.
+
+ Revision 1.32 2002/04/11 21:29:58 jongfoster
+ Documenting Win32 release procedure
+
+ Revision 1.31 2002/04/11 09:32:52 oes
+ more nits
+
+ Revision 1.30 2002/04/11 09:24:53 oes
+ nits
+
+ Revision 1.29 2002/04/10 18:45:14 swa
+ generated
+
+ Revision 1.28 2002/04/08 22:59:26 hal9
+ Version update. Spell chkconfig correctly :)
+
Revision 1.27 2002/04/08 15:31:18 hal9
Touch ups to documentation section.