<!entity p-intro SYSTEM "privoxy.sgml">
<!entity history SYSTEM "history.sgml">
<!entity seealso SYSTEM "seealso.sgml">
-<!entity p-version "3.0.27">
+<!entity p-version "3.0.29">
<!entity p-status "UNRELEASED">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
<!entity my-copy "©"> <!-- kludge for docbook2man -->
]>
<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
+ File : doc/source/developer-manual.sgml
Purpose : developer manual
- This file belongs into
- ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 2.83 2017/06/08 13:08:39 fabiankeil Exp $
-
- Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
<ulink url="https://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
- &my-copy; 2001-2016 by
+ &my-copy; 2001-2020 by
<ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
-
- <pubdate>$Id: developer-manual.sgml,v 2.83 2017/06/08 13:08:39 fabiankeil Exp $</pubdate>
-
<!--
Note: this should generate a separate page, and a live link to it.
<para>
The first step is to join the <ulink
url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel mailing list</ulink>.
- You can submit your ideas, or even better patches. Patches are best
+ 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.
</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).
+ You will also need to have a git package installed, which will
+ entail having ssh installed as well, in order to access the git 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), you can
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="cvs"><title>The CVS Repository</title>
+ <sect1 id="git"><title>The Git Repository</title>
<para>
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
+ need write access to our holy grail, the Git repository. One of the
team members will need to set this up for you. Please read
- this chapter completely before accessing via CVS.
+ this chapter completely before accessing via Git.
</para>
- <sect2 id="cvsaccess"><title>Access to CVS</title>
+ <sect2 id="gitaccess"><title>Access to Git</title>
+ <para>
+ The project's Git repository is hosted at the
+ <ulink url="https://privoxy.org/">Privoxy website</ulink>.
+ For Privoxy team members with push privileges the Git repository URL is
+ <literal>ssh://git@git.privoxy.org:23/git/privoxy.git</literal>.
+ </para>
+ <para>
+ Contributors without push privileges can
+ <quote>git clone https://www.privoxy.org/git/privoxy.git</quote>.
+ </para>
<para>
- The project's CVS repository is hosted on
- <ulink url="https://sourceforge.net/">SourceForge.</ulink>
- For historical reasons, the CVS server is
- called <literal>ijbswa.cvs.sourceforge.net</literal>, the repository is
- called <literal>ijbswa</literal>, and the source tree module is called
- <literal>current</literal>.
+ The central repository is called <literal>privoxy</literal>, and the
+ source branch is called <literal>master</literal>. Subfolders exist
+ within the project for target-dependent build and packaging tools, each
+ including the name of the target operating system in their name (e.g.
+ Windows, OSXPackageBuilder, debian). There is a webview of the Git
+ hierarchy at
+ <ulink url="https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree">
+ https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree</ulink>,
+ which might help with visualizing how these pieces fit together.
</para>
</sect2>
- <sect2 id="cvsbranches">
+ <sect2 id="gitbranches">
<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://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/"
- >http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/</ulink>,
- which might help with visualizing how these pieces fit together.
+ Whilst the central repository contains only the master branch, developers
+ are of course free to create branches in their local repositories as they
+ develop features, fixes, or update the target-dependent tools. Only once
+ such changes are fully tested ought they be pushed back to the central
+ repository master branch.
</para>
<!--
<para>
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
+ had prior testing before being committed to Git. (See <link
linkend="versionnumbers">Version Numbers</link> below for details on
versioning.)
</para>
-->
</sect2>
- <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
+ <sect2 id="gitcommit"><title>Git 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. <!-- There are differing guidelines for the stable branch and the
- main development trunk, and --> We expect anyone with CVS access to strictly
+ main development trunk, and --> We expect anyone with Git access to strictly
adhere to the following guidelines:
</para>
If necessary, prepare the commit messages in advance.
</para></listitem>
<listitem><para>
- Before changing things on CVS, make sure that your changes are in line
+ Before changing things on Git, make sure that your changes are in line
with the team's general consensus on what should be done.
</para></listitem>
<listitem>
</listitem>
<listitem>
<para>
- Alternately, proposed changes can be submitted as patches to the patch tracker on
- Sourceforge first: <ulink
- url="https://sourceforge.net/tracker/?group_id=11118&atid=311118">https://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
+ Alternately, proposed changes can be submitted as patches output by
+ <literal>git format-patch</literal> to the privoxy-devel mailing list
+ or alternatively to the patch tracker on Sourceforge:
+ <ulink url="https://sourceforge.net/tracker/?group_id=11118&atid=311118">
+ https://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
Then ask for peer review.
</para>
</listitem>
<para>
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. HTML versions are also being kept in CVS under
+ Git. HTML versions are also being kept in Git under
<filename>doc/webserver/*</filename>.
</para>
<para>
</para>
<para>
Documentation writers should please make sure documents build
- successfully before committing to CVS, if possible.
+ successfully before committing to Git, if possible.
</para>
<para>
How do you update the webserver (i.e. the pages on privoxy.org)?
</orderedlist>
<para>
- Finished docs should be occasionally submitted to CVS
+ Finished docs should be occasionally submitted to Git
(<filename>doc/webserver/*/*.html</filename>) 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
<para>
Some text goes here.
</para>
- </literallayout>
+</literallayout>
<para>
Tags marking individual words, or few words, should be in-line:
</para>
<literallayout>
Just to <emphasis>emphasize</emphasis>, some text goes here.
- </literallayout>
+</literallayout>
</listitem>
<listitem>
<para>
</para>
</itemizedlist>
</para>
- </literallayout>
+</literallayout>
<para>
This makes it easier to find the text amongst the tags ;-)
</para>
the finished doc at that point.
</para>
</listitem>
+
<listitem>
<para>
Commonly used <quote>internal entities</quote>:
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
/*********************************************************************
*
- * File : $S<!-- Break CVS Substitution -->ource$
+ * File : $Source
*
* Purpose : (Fill me in with a good description!)
*
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
/*********************************************************************
*
- * File : $S<!-- Break CVS Substitution -->ource$
+ * File : $Source
*
* Purpose : (Fill me in with a good description!)
*
</listitem>
<listitem>
<para>
+ <!-- FIXME this is not the way it works anymore -->
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
<listitem>
<para>
Z, the point or sub version, represents a release of the software within a branch.
- It is therefore incremented immediately before each code freeze.
+ It is therefore incremented immediately after each software release.
+ <!-- FIXME this is not the way it works any more
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
+ while the odd ones denote the evolving state of the sources on Git in between.
+ It follows that Z is odd on Git 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.
+ This ensures that builds from Git snapshots are easily distinguished from released versions.
+ didn't Fabian get rid of the even=stable, odd=dev convention for release numbering? -->
The point version is reset to zero when the minor changes.
</para>
<para>
</listitem>
</itemizedlist>
<para>
- In summary, the main CVS trunk is the development branch where new
+ In summary, the main Git 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
<para>
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
+ main trunk, since these are separate development trees within Git. If you
are working on both, then this would require at least two separate check
outs (i.e main trunk, <emphasis>and</emphasis> the stable release branch,
which is <literal>v_3_0_branch</literal> at the moment).
</sect2>
<sect2 id="beforerelease">
- <title>Before the Release: Freeze</title>
+ <title>Before the Release</title>
<para>
The following <emphasis>must be done by one of the
developers</emphasis> prior to each new release.
</para>
- <itemizedlist>
- <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
Make sure that everybody who has worked on the code in the last
couple of days has had a chance to yell <quote>no!</quote> in case
they have pending changes/fixes in their pipelines. Announce the
freeze so that nobody will interfere with last minute changes.
- </para>
+ </para>
</listitem>
<listitem>
<para>
- Increment the version number (point from odd to even in development
- branches!) in <filename>configure.in</filename> and update the code
- status (CODE_STATUS="xxx") to one of "alpha", "beta" or "stable".
- Rebuild configure and GNUMakefile to make sure the updated values are
- being used.
+ Update the code status (CODE_STATUS="xxx") in configure.in to one of
+ "alpha", "beta" or "stable".
</para>
</listitem>
<listitem>
<para>
- Use the dok-release target to update the sgml documentation source files.
+ Rebuild configure and GNUMakefile to make sure the updated values are being used.
+ </para>
+
+ <programlisting>
+$ autoheader && autoconf # rebuild configure
+$ ./configure # rebuild GNUmakefile
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ <command>make dok-release</command> to update the sgml documentation source files.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- All documentation should be rebuild after the version bump.
- Finished docs should be then be committed to CVS (for those
+ Create the change log:
+ </para>
+ <programlisting>
+ $ git tag
+ # to see the tags
+ $ git log [last release tag]..HEAD > /tmp/log
+ # get the commit log since the last release
+ $ utils/makeChangeLog /tmp/log > /tmp/change.log
+ # reformat the commit log
+</programlisting>
+ <para>
+ Edit <filename>/tmp/change.log</filename> to remove trivial
+ changes and group the changes under general headings like:
+ </para>
+ <programlisting>
+- Bug fixes:
+- Action file improvements:
+- Filter file improvements:
+- General improvements:
+- Documentation improvements:
+- Build system improvements:
+- Code cleanups:
+- Privoxy-Log-Parser:
+- Privoxy-Regression-Test:
+</programlisting>
+ <para>
+ Add the contents of <filename>/tmp/change.log</filename> to the
+ start of <filename>ChangeLog</filename> and re-create
+ <filename>doc/source/changelog.sgml</filename>:
+ </para>
+ <programlisting>
+ $ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ All developers should look at the <filename>ChangeLog</filename> and
+ make sure noteworthy changes are referenced.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All documentation should be rebuilt:
+ <programlisting>
+ $ make man
+ $ make dok
+ $ make dok-man
+ $ make dok-tidy
+ $ make config-file
+</programlisting>
+ Finished docs should be then be committed to Git (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)
fall in this category. README, 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.
+ should all also be committed to Git for other packagers. The
+ formal docs should be uploaded to the webserver. See the section
+ <ulink url="webserver-update.html">"Updating the webserver"</ulink>
+ in this manual for details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Commit all files that were changed in the above steps!</emphasis>
</para>
</listitem>
<listitem>
</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>
- </listitem>
- <listitem>
- <para>
- Tag all files in CVS with the version number with
+ Tag all files in Git with the version number with
<quote><command>cvs tag v_X_Y_Z</command></quote>.
Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
</para>
</listitem>
- <listitem>
- <para>
- If the release was in a development branch, increase the point version
- from even to odd (X.Y.(Z+1)) again in <filename>configure.in</filename> and
- commit your change.
- </para>
- </listitem>
<listitem>
<para>
On the webserver, copy the user manual to a new top-level directory
<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> (just press return when
+ the right version from Git into an empty directory</emphasis> (just press return when
asked for a password):
</para>
<para>
<emphasis>Do NOT change</emphasis> a single bit, including, but not limited to
- version information after export from CVS. This is to make sure that
+ version information after export from Git. This is to make sure that
all release packages, and with them, all future bug reports, are based
on exactly the same code.
</para>
interest (and possibly renamed to <filename>index.html</filename>).
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
+ this, it is in Git as
<filename>doc/webserver/man-page/privoxy-man-page.html</filename>,
and should be included along with the manuals. There is also a
css stylesheets that can be included for better presentation:
packages" above).
</para>
<para>
- As the only exception to not changing anything after export from CVS,
+ As the only exception to not changing anything after export from Git,
now examine the file <filename>privoxy-</filename><replaceable class="parameter">dist</replaceable><filename>.spec</filename>
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
</para>
</sect3>
- <sect3 id="newrelease-windows"><title>Windows</title>
+ <sect3 id="NEWRELEASE-WINDOWS"><title>Windows</title>
+ <!-- so annoying: docbook generated ids are UPPERCASE so
+ links to "whatever.html#idtag" DO NOT WORK!!
+ They have to be "whatever.html#IDTAG".
+ So be consistent and use uppercase on the definition.
+ -->
<para>
- Use the <ulink url="http://www.fruitbat.org/Cygwin/index.html#cygwincirca">
- Cygwin Time Machine</ulink> to install the last 1.5 version of Cygwin.
- Run the following commands from within the Cygwin 1.5 bash shell.
+ Note that the docbook generated files might need some hand editing,
+ so the Windows build makefile does not rebuild the docs.
</para>
+
<para>
First, <emphasis>make sure that you have freshly exported the right
version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then get the Windows setup module:
+ packages" above).
+ <!-- XXX ??? are we still basing releases off a tarball???
+ -->
</para>
- <programlisting>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
-</programlisting>
<para>
Then you can build the package. This is fully automated, and is
- controlled by <filename>winsetup/GNUmakefile</filename>.
+ controlled by <filename>windows/GNUmakefile</filename>.
All you need to do is:
</para>
<programlisting>
- cd winsetup
+ cd windows
make
</programlisting>
<para>
Now you can manually rename <filename>privoxy_setup.exe</filename> to
- <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
- SourceForge. When releasing the package on SourceForge, use the release notes
+ <filename>privoxy_setup_X.Y.Z.exe</filename>, and the <filename>build</filename>
+ directory to <filename>privoxy_X.Y.Z</filename>.
+ Create a .zip file of the newly renamed <filename>privoxy_X.Y.Z</filename> directory,
+ GPG sign the installer and zip file,
+ </para>
+ <programlisting>
+ $ gpg --armor --detach --sign <filename>privoxy_setup_X.Y.Z.exe</filename>
+ $ gpg --armor --detach --sign <filename>privoxy_X.Y.Z.zip</filename>
+</programlisting>
+ <para>
+ and upload the files to SourceForge.
+ </para>
+
+ <para>
+ When releasing the package on SourceForge, use the release notes
and Change Log from the source tarball package.
</para>
</sect3>
packages" above).
</para>
<para>
- There are three modules available in the CVS repository for use on Mac
+ There are three modules available in the Git repository for use on Mac
OS X, though technically only two of them generate a release (the other
can be used to install from source).
</para>
<title>OSXPackageBuilder module</title>
<para>
The OSXPackageBuilder module generates OS X installer packages
- supporting all Macs running OS X 10.4 and above. Obtain it from CVS as
+ supporting all Macs running OS X 10.4 and above. Obtain it from Git as
follows into a folder parallel to the exported privoxy source:
</para>
<programlisting>
supports only Intel Macs running OS X 10.6 or higher.</emphasis>
</para>
<para>
- Check out the module from CVS as follows into a folder parallel to the
+ Check out the module from Git as follows into a folder parallel to the
exported privoxy source:
</para>
<programlisting>
from source on a single machine.
</para>
<para>
- Check out the module from CVS as follows into a folder parallel to the
+ Check out the module from Git as follows into a folder parallel to the
exported privoxy source:
</para>
<programlisting>
to SourceForge, and go through the release steps. The upload
is done via FTP:
</para>
- <itemizedlist>
- <listitem>
-
Upload to: <ulink url="ftp://upload.sourceforge.net/incoming">ftp://upload.sourceforge.net/incoming</ulink>
- </para>
- </listitem>
- <listitem>
- user: <literal>anonymous</literal>
- </para>
- </listitem>
- <listitem>
- password: <literal>ijbswa-developers@lists.sourceforge.net</literal>
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Upload to: <ulink url="ftp://upload.sourceforge.net/incoming">ftp://upload.sourceforge.net/incoming</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ user: <literal>anonymous</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ password: <literal>ijbswa-developers@lists.sourceforge.net</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
<para>
Or use the <command>make</command> targets as described above.
</para>
<para>
- Once this done go to <ulink
- url="https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
- >https://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
+ Once this done go to
+ <ulink url="https://sourceforge.net/project/admin/editpackages.php?group_id=11118">
+ https://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
making sure you are logged in. Find your target platform in the
second column, and click <literal>Add Release</literal>. You will
then need to create a new release for your package, using the format
<title>After the Release</title>
<para>
When all (or: most of the) packages have been uploaded and made available,
- send an email to the <ulink url="mailto:privoxy-announce@lists.privoxy.org">announce
- mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
+ send an email to the
+ <ulink url="mailto:privoxy-announce@lists.privoxy.org">announce mailing
+ list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
include the
- <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">download
- location</ulink>, the release notes and the Changelog. Also, post an
+ <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">
+ download 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). Other news sites
and release oriented sites, such as Freshmeat, should also be notified.
</para>
+ <para>
+ Then update the source code for the next version to be released:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Increment the version number and change the code status to "UNRELEASED"
+ in <filename>configure.in</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rebuild configure (<quote><command>autoheader && autoconf</command></quote>)
+ and GNUMakefile (<quote><command>./configure</command></quote>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <quote><command>make dok-release</command></quote> to update the sgml documentation source files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Commit all your changes.
+ </para>
+ </listitem>
+ </itemizedlist>
+
</sect2>
</sect1>
<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
- [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.)
+ [now in Git, 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?
+ Next, commit any changes from the above steps to Git. All set?
If these are docs in the stable branch, then do:
</para>
<programlisting>
projects / privoxy.git / blobdiff