X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=aed9fc5542683e71d9e2fb8cf60232028d5b75b9;hb=962ed628ec708d487afd1494813141fc048143d6;hp=a8c8fa2c919bd8dca1be22879bd22e7bac677ce2;hpb=8023259b48217910c1dd8038ffc16a57f9a10f37;p=privoxy.git
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index a8c8fa2c..aed9fc55 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-2008 by
+ Privoxy Developers
+
+
+
+
+ $Id: developer-manual.sgml,v 2.22 2008/08/30 15:37:35 fabiankeil Exp $
+
+
+
@@ -65,23 +81,28 @@
]]>
- 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. Note that it's currently out of date
+ and may not be entirely correct. As always, patches are welcome.
+
- &p-intro;
+
+ 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 on how to contact the developers.
+ Please see the Contact section
+ on how to contact the developers.
-
@@ -89,18 +110,9 @@
-
-
-
-
-
-
-
-
-
- Introduction
+ Introduction
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), you can
+ also refer to the extensive comments in the source code. In fact,
+ reading the code is recommended in any case.
+
+
- 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 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.
+
-
-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 ijbswa.cvs.sourceforge.net, the repository is
+ called ijbswa, and the source tree module is called
+ current.
+
+
+
+
+ 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. 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:
+
+
+
+
+ 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.
+
+
+ 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 committed (e.g. when changing the signature of a function),
+ then commit all files one after another, without long delays in between.
+ If necessary, prepare the commit messages in advance.
+
+
+ Before changing things on CVS, make sure that your changes are in line
+ 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.
+
+
+
+
+
+
+
+
+
Documentation Guidelines
- All formal documents are maintained in docbook SGML and located in the
- doc/source directory. You will need
- docbook and the docbook
- stylesheets (or comparable alternatives), and either
- jade or openjade
- (recommended) installed in order to build docs from source. Currently
- there is doc/source/* directory. You will need
+ Docbook, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ and either jade or
+ openjade (recommended) installed in order to
+ build docs from source. Currently there is user-manual,
- FAQ, and,
- of course this, the developer-manual in this
- format. The README, is also now maintained
- as SGML. The README in the top-level source
- directory is a generated file. DO NOT edit this
- directly. Edit the SGML source!
+ FAQ, and, of
+ course this, the developer-manual in this format.
+ 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
+ generated files! Also, the Privoxy index.html (and a
+ variation on this file, privoxy-index.html,
+ meant for inclusion with doc packages), are maintained as SGML as well.
+ DO NOT edit these directly. Edit the SGML source, or
+ contact someone involved in the documentation.
- Other, less formal documents (e.g. AUTHORS, LICENSE) are maintained as
- plain text files in the toplevel source directory. At least for the
- time being.
+ config requires some special handling. The reason it
+ is maintained this way is so that the extensive comments in the file
+ mirror those in user-manual. But the conversion
+ process requires going from SGML to HTML to text to special formatting
+ required for the embedded comments. Some of this does not survive so
+ well. Especially some of the examples that are longer than 80 characters.
+ The build process for this file outputs to config.new,
+ which should be reviewed for errors and mis-formatting. Once satisfied
+ that it is correct, then it should be hand copied to
+ config.
+
+
+ Other, less formal documents (e.g. LICENSE) 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. Or HTML versions can be downloaded from the www.privoxy.org website, which
- should be fairly current. (This is only a temporary solution.)
+ 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
make dok, or alternately
make redhat-dok. If you have problems,
try both. The build process uses the document SGML sources in
- doc/source to update all text files in
- doc/text and to update all HTML
- documents in doc/webserver.
+ doc/source/*/* to update all text files in
+ doc/text/ and to update all HTML
+ documents in doc/webserver/.
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)?
@@ -202,7 +394,8 @@ following guidelines for changing stuff in the code. If it is
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
@@ -212,30 +405,40 @@ 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).
+
Quickstart to Docbook and SGML
If you are not familiar with SGML, it is a markup language similar to HTML.
- In fact, HTML is an SGML application. Both use tags
- to format text and other content. SGML tags are much more varied,
- and flexible, but do much of the same kinds of things. The tags,
- or elements
, are definable in SGML. There is no
- set standards
. Since we are using
- Docbook, our tags are those that are
- defined by Docbook. Much of how the
- finish document is rendered is determined by the stylesheets
.
- The stylesheets determine how each tag gets translated to HTML, or
- other formats.
+ Actually, not a mark up language per se, but a language used to define
+ markup languages. In fact, HTML is an SGML application. Both will use
+ tags
to format text and other content. SGML tags can be much
+ more varied, and flexible, but do much of the same kinds of things. The tags,
+ or elements
, are definable in SGML. There is no set
+ standards
. Since we are using
+ Docbook, our tags are those that are defined by
+ Docbook. Much of how the finish document is
+ rendered is determined by the stylesheets
.
+ The stylesheets determine how each tag gets translated to HTML, or other
+ formats.
- Tags in SGML need to be always closed
. If not, you
- will likely generate errors. Example:
- <title>My Title</title>. They are
- also case-insensitive, but we strongly suggest using all lower
- case. This keeps compatibility with [Docbook] XML.
+ Tags in Docbook SGML need to be always closed
. If not, you
+ will likely generate errors. Example: <title>My
+ Title</title>. They are also case-insensitive, but we
+ strongly suggest using all lower case. This keeps compatibility with
+ [Docbook] XML.
@@ -256,51 +459,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.
-
-
- <emphasis></emphasis>, 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.
+
-
Privoxy Documentation Style
@@ -321,8 +530,8 @@ following guidelines for changing stuff in the code. If it is
- Tags delimiting a block of text should be on their own line.
- Like:
+ Tags delimiting a block of text (even small
+ blocks) should be on their own line. Like:
<para>
Some text goes here.
@@ -336,8 +545,9 @@ following guidelines for changing stuff in the code. If it is
- Tags should be nested and step indented like:
-
+ Tags should be nested and step indented for block text like: (except
+ in-line tags)
+
<para>
<itemizedlist>
<para>
@@ -362,26 +572,28 @@ following guidelines for changing stuff in the code. If it is
Do not hesitate to make comments. Comments can either use the
<comment> element, or the <!-- --> style comment
- familiar from HTML.
+ familiar from HTML. (Note in Docbook v4.x <comment> is
+ replaced by <remark>.)
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.
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:
@@ -434,15 +646,15 @@ following guidelines for changing stuff in the code. If it is
p-version entity that contains the current
Privoxy version string. You are strongly
encouraged to use these where possible. Some of these obviously
- require re-setting with each release. A sampling of custom entities are
- listed below. See any of the main docs for examples.
+ require re-setting with each release (done by the Makefile). A sampling of
+ custom entities are listed below. See any of the main docs for examples.
- Re-cyclable boilerplate
text entities are defined like:
+ Re- boilerplate
text entities are defined like:
<!entity supported SYSTEM "supported.sgml">
@@ -463,15 +675,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.
@@ -521,8 +733,8 @@ following guidelines for changing stuff in the code. If it is
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
@@ -536,13 +748,13 @@ following guidelines for changing stuff in the code. If it is
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 ...
}
@@ -570,28 +782,28 @@ 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:
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.
@@ -617,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*/
}
@@ -636,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 */
@@ -713,7 +925,7 @@ short DoSomethingVeryImportant(
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
@@ -721,7 +933,7 @@ or:
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */
@@ -737,7 +949,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.
@@ -764,7 +976,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.
@@ -906,11 +1118,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:
@@ -938,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
@@ -972,7 +1184,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-)
@@ -991,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 )
@@ -1018,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 ();
@@ -1037,7 +1249,7 @@ FunctionName();
int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
@@ -1049,18 +1261,18 @@ 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
- 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.
@@ -1119,16 +1331,16 @@ 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-discrection if and only if the
+ Status: developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.
@@ -1149,9 +1361,9 @@ struct *ptr = NULL;
Example:
-ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();
+should_we_block_this();
+contains_an_image();
+is_web_page_blank();
@@ -1180,7 +1392,7 @@ IsWebPageBlank();
Example:
-for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}
@@ -1189,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,
@@ -1201,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.
@@ -1281,7 +1493,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.
@@ -1354,9 +1566,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.
@@ -1402,7 +1614,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 ) ) */
@@ -1413,9 +1625,9 @@ 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.
+ load_config). Or it may really be an abort condition.
Status: Programmer discretion is advised.
@@ -1474,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.
@@ -1507,10 +1718,10 @@ 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-discrection.
+ Status: developer-discretion.
@@ -1520,7 +1731,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
@@ -1529,7 +1740,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'.
@@ -1545,7 +1756,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/destructor type function to accommodate this.
Example:
@@ -1558,7 +1769,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).
@@ -1585,16 +1796,16 @@ static void unload_re_filterfile( void *f ) { ... }
"Uncertain" new code and/or changes to
- exitinst code, use FIXME
+ existing code, use FIXME or XXX
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:
@@ -1609,7 +1820,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).
@@ -1622,14 +1833,14 @@ static void unload_re_filterfile( void *f ) { ... }
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id$";
/*********************************************************************
*
* 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
@@ -1651,8 +1862,9 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:
* 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$
@@ -1674,7 +1886,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.
@@ -1682,19 +1894,15 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id$"
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
+ * Copyright : Written by and Copyright (C) 2001-2008
+ * the Privoxy team. http://www.privoxy.org/
*
* This program is free software; you can redistribute it
* and/or modify it under the terms of the GNU General
@@ -1711,8 +1919,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$
@@ -1778,13 +1987,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.
@@ -1834,31 +2036,123 @@ at sourceforge. Three simple steps:
intelligent (keep it short and precise).
- Do not mail to the mailinglist (we cannot keep track on issues there).
+ Do not mail to the mailing list (we cannot keep track on issues there).
- Releasing a new version
+ Releasing a New Version
- 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.
+ 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.
+
+ 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 (e.g. 3.0.0), 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 bug-fixes are made, and 2N+1, the development branch, in
+ which the further development of Privoxy takes
+ place.
+ This enables us to turn the code upside down and inside out, while at the same time
+ providing and maintaining a stable version.
+ The minor is reset to zero (and one) when the major is incremented. When a development
+ branch has matured to the point where it can be turned into stable, the old stable branch
+ 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
+ new stable branch 2N+2, and a new development branch 2N+3 is opened.
+
+
+
+
+ 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.
+
+
+ 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).
+
+
- 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.
@@ -1866,136 +2160,366 @@ 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. (RPM spec files
+ will need to be incremented as well.)
- 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";'
+
+
+
+ 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.
+
- 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.
+ 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.
- 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).
+ All developers should look at the ChangeLog and
+ make sure noteworthy changes are referenced.
+
+
+
+
+ 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
.
+ 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).
- Update the webserver
+
+ 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 (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@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
+
+
+
+
+ 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.
+
+
+
+
+ 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
+ on the Sourceforge release process below that.
+
+
+
+ Note on Privoxy Packaging
+
+ Please keep these general guidelines in mind when putting together
+ your package. These apply to all platforms!
+
+
+
+
+
+ Privoxy requires
+ write access to: all *.action files, all
+ logfiles, and the trust file. You will
+ need to determine the best way to do this for your platform.
+
+
+
+
+ Please include up to date documentation. At a bare minimum:
+
+
+
+ LICENSE (top-level directory)
+
+
+
+
+ README (top-level directory)
+
+
+
+
+ AUTHORS (top-level directory)
+
+
+
+
+ man page (top-level directory, Unix-like
+ platforms only)
+
+
+
+
+ The User Manual (doc/webserver/user-manual/)
+
+
+
+
+ FAQ (doc/webserver/faq/)
+
+
+
+ Also suggested: Developer Manual
+ (doc/webserver/developer-manual) and ChangeLog
+ (top-level directory). FAQ and the manuals are
+ HTML docs. There are also text versions in
+ doc/text/ which could conceivably also be
+ included.
+
+
+ The documentation has been designed such that the manuals are linked
+ to each other from parallel directories, and should be packaged
+ that way. privoxy-index.html can also be
+ included and can serve as a focal point for docs and other links of
+ interest (and possibly renamed to index.html).
+ This should be one level up from the manuals. There is a link also
+ on this page to an HTMLized version of the man page. To avoid 404 for
+ this, it is in CVS as
+ doc/webserver/man-page/privoxy-man-page.html,
+ and should be included along with the manuals. There is also a
+ css stylesheets that can be included for better presentation:
+ p_doc.css. This should be in the same directory
+ with privoxy-index.html, (i.e. one level up from
+ the manual directories).
+
+
+
+
+ user.action 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 (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.
+
+
+
- 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
+ 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).
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+ 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
-
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
+
You will need a mix of development tools.
@@ -2011,55 +2535,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
@@ -2067,82 +2594,105 @@ 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@ijbswa.cvs.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:
-
-
-
- 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.
-
-
+ First, make sure that you have freshly exported the
+ right version into an empty directory. (See
+ "Building and releasing packages" above). Then add a log
+ entry to debian/changelog, if it is not
+ already there, for example by running:
+
+
+
+ debchange -v &p-version;-&p-status;-1 "New upstream version"
+
+
+
+ Then, run:
+
+
+
+ dpkg-buildpackage -rfakeroot -us -uc -b
+
+
+
+ This will create
+ ../privoxy_&p-version;-&p-status;-1_i386.deb
+ which can be uploaded. To upload the package to Sourceforge, simply
+ issue
+
+
+
+ make debian-upload
+
+
+
- Mac OSX
+ Mac OS X
- 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 OS X 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
-
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
+
+
+
+ Then run:
- From the osxsetup directory, run:
+ cd osxsetup
build
-
+
This will run autoheader, autoconf and
@@ -2155,52 +2705,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
-
+ 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:
+ Login to Sourceforge's compile-farm 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:
@@ -2208,134 +2746,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:
@@ -2343,18 +2818,151 @@ 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 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
+ 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 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.
+
+
+
+ Update the Webserver
+
+ 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 stable-branch documentation source
+ SGML files, do:
+
+
+
+ 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,
+ doc/pdf/*.pdf and
+ doc/webserver/index.html automatically.
+
+
+ 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
+ [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
+ the doc/webserver/* directory (or
+ create new directories under doc/webserver).
+
+
+ Next, commit any changes from the above steps to CVS. All set?
+ If these are docs in the stable branch, 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. Also, please do not
+ upload docs from development branches or versions. The publicly posted
+ docs should be in sync with the last official release.
+
+
+
Contacting the developers, Bug Reporting and Feature Requests
@@ -2362,22 +2970,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
@@ -2408,6 +3024,183 @@ 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 2.22 2008/08/30 15:37:35 fabiankeil
+ Update entities.
+
+ Revision 2.21 2008/08/16 08:51:28 fabiankeil
+ Update version-related entities.
+
+ 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.46.2.5 2002/08/09 01:15:12 hal9
+ Added some notes on pre-release steps (test builds first, update ChangeLog).
+
+ Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd
+ Fixed a little formatting. Clarified debian section.
+
+ Revision 1.46.2.3 2002/05/28 04:32:45 hal9
+ Change hints on bundling index.html to privoxy-index.html
+
+ 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
+ Add releasing information about Debian.
+
+ Revision 1.47 2002/05/26 04:55:11 mal0rd
+ Added debian-dist and debian-upload targets. Also documented usage.
+
+ Revision 1.46 2002/05/22 17:15:00 oes
+ Updated intro
+
+ Revision 1.45 2002/05/19 23:01:54 hal9
+ Add small section on general packaging guidelines (e.g. actions files must
+ be writable).
+
+ Revision 1.44 2002/05/15 03:55:17 hal9
+ Fix ulink -> link, and minor modification to release process section for
+ clarification.
+
+ Revision 1.43 2002/05/10 01:48:19 hal9
+ This is mostly proposed copyright/licensing additions and changes. Docs
+ are still GPL, but licensing and copyright are more visible. Also, copyright
+ 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.
+
+ Revision 1.26 2002/04/07 23:50:08 hal9
+ Documentation changes to reflect HTML docs now in CVS, and new generated files
+ list.
+
+ Revision 1.25 2002/04/06 05:07:28 hal9
+ -Add privoxy-man-page.sgml, for man page.
+ -Add authors.sgml for AUTHORS (and p-authors.sgml)
+ -Reworked various aspects of various docs.
+ -Added additional comments to sub-docs.
+
Revision 1.24 2002/04/04 21:33:37 hal9
More on documenting the documents.
@@ -2425,7 +3218,7 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
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