This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.1 2002/07/29 22:08:40 jongfoster Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $</pubdate>
<!--
-->
-<abstract>
<![%dummy;[
<para>
<!-- end boilerplate -->
<para>
+ 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 <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
Please see <link linkend="contact">the Contact section</link>
url="mailto:developers@privoxy.org">the list</ulink> and wait until a
project manager has added you.
</para>
+ <para>
+ 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).
+ </para>
<para>
For the time being (read, this section is under construction), please
refer to the extensive comments in the source code.
</para>
</sect2>
- <sect2 id="cvscommit"><title>CVS Commit Guideline</title>
+ <sect2 id="cvsbranches">
+ <title>Branches</title>
+ <para>
+ Within the CVS repository, there are modules and branches. As
+ mentioned, the sources are in the <literal>current</literal>
+ <quote>module</quote>. Other modules are present for platform specific
+ issues. There is a webview of the CVS hierarchy at <ulink
+ url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/</ulink>,
+ which might help with visualizing how these pieces fit together.
+ </para>
+ <para>
+ Branches are used to fork a sub-development path from the main trunk.
+ Within the <literal>current</literal> module where the sources are, there
+ is always at least one <quote>branch</quote> 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 <emphasis>only used for bugfixes</emphasis>, which have
+ had prior testing before being committed to CVS. (See <link
+ linkend="versionnumbers">Version Numbers</link> below for details on
+ versioning.)
+ </para>
+ </sect2>
+
+ <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
<para>
The source tree is the heart of every software project. Every effort must
be made to ensure that it is readable, compilable and consistent at all
- times. We therefore ask anyone with CVS access to strictly adhere to the
- following guidelines:
+ times. There are differing guidelines for the stable branch and the
+ main development trunk, and we ask anyone with CVS access to strictly
+ adhere to the following guidelines:
+ </para>
+
+ <para>
+ Basic Guidelines, for all branches:
+ </para>
+ <para>
<itemizedlist>
<listitem><para>
Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
</para></listitem>
<listitem><para>
Before changing things on CVS, make sure that your changes are in line
- with the team's general consensus on what should be done (see below).
+ with the team's general consensus on what should be done.
</para></listitem>
+ <listitem>
+ <para>
+ Note that near a major public release, we get more cautious.
+ There is always the possibility to submit a patch to the <ulink
+ url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch
+ tracker</ulink> instead.
+ </para>
+ </listitem>
</itemizedlist>
</para>
+
+ <para>
+ Stable branches are handled with more care, especially after the
+ initial *.*.0 release, and we are just in bugfix mode. In addition to
+ the above, the below applies only to the stable branch (currently the
+ v_3_0_branchpoint branch):
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem><para>
+ Do <emphasis>not commit anything</emphasis> into the stable branch,
+ unless immediately before a new release! There needs to be testing
+ done before it hits CVS, and to ensure that all changes are
+ appropriate just to fix whatever the problem is.
+ </para></listitem>
+ <listitem>
+ <para>
+ Submit any proposed changes as patches first to the patch tracker on
+ Sourceforge: <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=311118">http://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
+ Then ask for peer review.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Do not commit <emphasis>anything</emphasis> unless your patches
+ been well tested first, by other members of the project,
+ and has prior approval of the project leaders or consensus of the
+ devel list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Do not even think about anything except bugfixes. No new features!
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
</sect2>
+<!--
+ This sounds vague, dated, and out of step with current development style.
+ Removing 09/03/02, HB.
+
<sect2 id="cvswhenask"><title>Discussing Changes First</title>
<para>
- We don't have a too formal policy on this, just use common sense. Hints: If it is..
- <orderedlist numeration="arabic">
+ We don't have a formal policy for the development branch, just use
+ common sense. Hints: If it is..
+ <orderedlist numeration="arabic">
<listitem><para>
..a bug-fix / clean-up / cosmetic thing: shoot
</para></listitem>
tracker</ulink> instead.
</para>
</sect2>
+ -->
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
variation on this file, <filename>privoxy-index.html</filename>,
meant for inclusion with doc packages), are maintained as SGML as well.
<emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
- contact someone involved in the documentation (at present Stefan and
- Hal).
+ contact someone involved in the documentation (at present Hal).
</para>
<para>
<filename>config</filename> requires some special handling. The reason it
which should be reviewed for errors and mis-formatting. Once satisfied
that it is correct, then it should be hand copied to
<filename>config</filename>.
-
</para>
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<listitem><para>
First, build the docs by running <computeroutput>make
dok</computeroutput> (or alternately <computeroutput>make
- redhat-dok</computeroutput>).
+ redhat-dok</computeroutput>). For PDF docs, do <computeroutput>make
+ dok-pdf</computeroutput>.
</para></listitem>
<listitem><para>
Run <computeroutput>make webserver</computeroutput> which copies all
<listitem>
<para>
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, TML, and PDF, but others are always a
future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<para>
First you need to determine which version number the release will have.
<application>Privoxy</application> version numbers consist of three numbers,
- separated by dots, like in X.Y.Z, where:
+ separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
<itemizedlist>
<listitem>
<para>
</listitem>
</itemizedlist>
</para>
+ <para>
+ 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. At that point, it
+ is mostly <quote>hands off</quote>. 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
+ <emphasis>before</emphasis> committing to a stable branch!
+
+ </para>
</sect2>
<listitem>
<para>
Increment the version number (point from odd to even in development
- branches!) in <filename>configure.in</filename>.
+ branches!) in <filename>configure.in</filename>. (RPM spec files
+ will need to be incremented as well.)
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- If the HTML documentation is not in sync with the SGML sources
- you need to regenerate and upload it to the webserver. (If in
- doubt, just do it.) See the Section "Updating the webserver" in
- this manual for details.
+ All documentation should be rebuild after the version bump.
+ Finished docs should be then be committed to CVS (for those
+ without the ability to build these). Some docs may require
+ rather obscure processing tools. <filename>config</filename>,
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <citetitle>User Manual</citetitle> 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 <citetitle>User Manual</citetitle>
+ link from the main page since we need to keep manuals for various
+ versions available). The CGI pages will link to something like
+ <literal>http://privoxy.org/$(VERSION)/user-manual/</literal>. 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.
</para>
</listitem>
+ <listitem>
+ <para>
+ All developers should look at the <filename>ChangeLog</filename> and
+ make sure noteworthy changes are referenced.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>Commit all files that were changed in the above steps!</emphasis>
<para>
For <emphasis>all</emphasis> types of packages, including the source tarball,
<emphasis>you must make sure that you build from clean sources by exporting
- the right version from CVS into an empty directory:</emphasis>.
+ the right version from CVS into an empty directory</emphasis> (just press return when
+ asked for a password):
</para>
<para>
maintainers to do this if you can't).
</para>
</listitem>
+ <listitem>
+ <para>
+ Packagers should do a <quote>clean</quote> 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.
+ </para>
+ </listitem>
</itemizedlist>
</para>
mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
include the
<ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
- location</ulink>, the release notes and the change log.
+ location</ulink>, 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).
</para>
</sect2>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="webserver-update"><title>Update the Webserver</title>
<para>
- When updating the webserver, please follow these steps to make
- sure that no broken links, inconsistent contents or permission
- problems will occur:
+ The webserver should be updated at least with each stable release. When
+ updating, please follow these steps to make sure that no broken links,
+ inconsistent contents or permission problems will occur (as it has many
+ times in the past!):
</para>
<para>
- If you have changed anything in the documentation source SGML files,
- do:
+ If you have changed anything in the stable-branch documentation source
+ SGML files, do:
</para>
<para>
<programlisting>
- make dok # (or make redhat-dok if make dok doesn't work for you)
+ make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
</programlisting>
</para>
<para>
That will generate <filename>doc/webserver/user-manual</filename>,
<filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
+ <filename>doc/webserver/faq</filename>,
+ <filename>doc/pdf/*.pdf</filename> and
<filename>doc/webserver/index.html</filename> automatically.
</para>
<para>
- If you changed the manual page source, generate
+ If you changed the manual page sources, generate
<filename>doc/webserver/man-page/privoxy-man-page.html</filename>
by running <quote><command>make man</command></quote>. (This is
- a separate target due to dependencies on some obscure perl scripts.
- See comments in <filename>GNUmakefile</filename>.)
+ a separate target due to dependencies on some obscure perl scripts
+ [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.)
</para>
<para>
If you want to add new files to the webserver, create them locally in
create new directories under <filename>doc/webserver</filename>).
</para>
<para>
- Next, commit any changes from the above steps to CVS. All set? Then do
+ Next, commit any changes from the above steps to CVS. All set?
+ If these are docs in the stable branch, then do:
</para>
<para>
<programlisting>
</para>
<para>
Please do <emphasis>NOT</emphasis> use any other means of transferring
- files to the webserver to avoid permission problems.
+ files to the webserver to avoid permission problems. Also, please do not
+ upload docs from development branches or versions. The publicly posted
+ docs should be in sync with the last official release.
</para>
</sect1>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
- Revision 1.50 2002/06/05 00:31:55 hal9
- Mass commit for new entities, most significantly so docs can read version
- and code status info from tmp files, so perl is no longer used. Also, docs can
- differentiate on alpha -> beta -> stable now.
+ Revision 1.46.2.8 2002/08/17 00:16:10 hal9
+ Add note on updating webserver for User-manual/CGI editor, which is version
+ dependent (and different from main UM link).
+
+ Revision 1.46.2.7 2002/08/14 17:29:25 hal9
+ Add small notes on post-release steps, and uploading docs to webserver.
+
+ Revision 1.46.2.6 2002/08/10 11:40:25 oes
+ Added disclaimer about probably being out-of-date and two small hints
- Revision 1.49 2002/06/03 00:28:16 hal9
- Sync with various changes from 3.0 branch. Add two new files for config stuff.
+ Revision 1.46.2.5 2002/08/09 01:15:12 hal9
+ Added some notes on pre-release steps (test builds first, update ChangeLog).
- Revision 1.51 2002/05/29 00:30:59 mal0rd
+ Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd
Fixed a little formatting. Clarified debian section.
- Revision 1.50 2002/05/28 04:32:45 hal9
+ Revision 1.46.2.3 2002/05/28 04:32:45 hal9
Change hints on bundling index.html to privoxy-index.html
- Revision 1.49 2002/05/26 17:04:24 hal9
+ Revision 1.46.2.2 2002/05/26 17:04:24 hal9
-Spellcheck, very minor edits, and sync across branches
Revision 1.48 2002/05/26 12:48:31 roro
projects / privoxy.git / commitdiff