<!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.30">
<!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-2021 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-2021 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>
<application>Privoxy</application>, as an heir to
- <application>Junkbuster</application>, is a Free Software project
- and the code is licensed under the GNU General Public License version 2.
+ <application>Junkbuster</application>, is a <ulink
+ url="https://www.privoxy.org/user-manual/copyright.html">Free Software</ulink> project.
As such, <application>Privoxy</application> 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,
<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
- submitted to the Sourceforge tracker set up for this purpose, but
- can be sent to the list for review too.
+ You can submit your ideas or, even better, patches.
+ Patches can also be submitted to the
+ <ulink url="https://sourceforge.net/p/ijbswa/patches/">Sourceforge patch tracker</ulink>.
</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,
+ 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 on the
+ <ulink url="https://www.privoxy.org/">Privoxy webserver</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>
+ Before pushing stuff, please rebase it on a current master so we get
+ an uncomplicated commit history. Avoid merges where possible.
+ </para>
+ <para>
+ Here's an example git sesssion that should result in a merge-free history:
+ </para>
+ <programlisting>
+fk@t520 ~/git/privoxy $git checkout master
+Switched to branch 'master'
+Your branch is up to date with 'origin/master'.
+# Make sure you have the latest changes
+fk@t520 ~/git/privoxy $git pull
+Already up to date.
+# Create a local banch for changes
+fk@t520 ~/git/privoxy $git checkout -b local-branch
+Switched to a new branch 'local-branch'
+# Create some change
+fk@t520 ~/git/privoxy $gmake dok dok-tidy
+[...]
+# Review your change
+fk@t520 ~/git/privoxy $git diff
+[...]
+# Commit your changes if they look goood
+fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/
+[local-branch 1abb7316] developer-manual: Regenerate
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+# Review your commit
+fk@t520 ~/git/privoxy $git show
+[...]
+# Go to the master branch
+fk@t520 ~/git/privoxy $git checkout master
+Switched to branch 'master'
+Your branch is up to date with 'origin/master'.
+# Make sure you are still in sync
+fk@t520 ~/git/privoxy $git pull
+[...]
+Already up to date.
+# Apply the commit you made to the local-branch
+fk@t520 ~/git/privoxy $git cherry-pick local-branch
+[master 046e85e2] developer-manual: Regenerate
+ Date: Tue Dec 15 05:10:07 2020 +0100
+ 1 file changed, 2 insertions(+), 2 deletions(-)
+# Make sure the history looks as expected
+fk@t520 ~/git/privoxy $git log -p
+# Finally push your change to the Privoxy repository
+fk@t520 ~/git/privoxy $git push
+[...]
+# Go back to the local branch
+fk@t520 ~/git/privoxy $git checkout local-branch
+# Rebase on top of master and continue hacking
+fk@t520 ~/git/privoxy $git rebase master
+Successfully rebased and updated refs/heads/local-branch.
+</programlisting>
<!--
<para>
Branches are used to fork a sub-development path from the main trunk.
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>
<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="https://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch
- tracker</ulink> instead.
+ url="https://sourceforge.net/p/ijbswa/patches/">patch
+ tracker</ulink> or the <ulink
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel mailing list</ulink>
+ instead.
</para>
</listitem>
</itemizedlist>
</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/p/ijbswa/patches/">
+ https://sourceforge.net/p/ijbswa/patches/</ulink>.
Then ask for peer review.
</para>
</listitem>
<para>
All formal documents are maintained in Docbook SGML and located in the
<computeroutput>doc/source/*</computeroutput> directory. You will need
- <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
+ <ulink url="https://www.docbook.org/">Docbook</ulink>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
and either <application>jade</application> or
<application>openjade</application> (recommended) installed in order to
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 <filename>config.new</filename>,
- 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>) are
<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 numeration="arabic">
<listitem><para>
First, build the docs by running <computeroutput>make
- dok</computeroutput>.
+ dok dok-tidy</computeroutput>.
</para></listitem>
<listitem><para>
Run <computeroutput>make webserver</computeroutput> which copies all
files from <computeroutput>doc/webserver</computeroutput> to the
- sourceforge webserver via scp.
+ sourceforge webserver via ssh.
</para></listitem>
</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>
<!-- ~~~~~ New section ~~~~~ -->
- <sect2><title>Privoxy Custom Entities</title>
+ <sect2 id="custom-entities"><title>Privoxy Custom Entities</title>
<para>
<application>Privoxy</application> documentation is using
a number of customized <quote>entities</quote> to facilitate
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!)
*
</sect2>
<!-- XXX: Document how to write test reports and where to send them -->
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect2 id="privoxy-regression-test"><title>Testing with <application>Privoxy-Regression-Test</application></title>
+ <para>
+ If you compiled, packaged or merely installed Privoxy, it is recommended to run
+ <application>Privoxy-Regression-Test</application> to verify that at least
+ the tested parts of <application>Privoxy</application> are working as expected.
+ </para>
+ <para>
+ This is actually pretty easy. For details, please see
+ <command>perldoc privoxy-regression-test.pl</command>.
+ </para>
+ <para>
+ Here is an example of what <application>Privoxy-Regression-Test</application> can do for you:
+ </para>
+ <programlisting>
+# Run all the tests
+fk@t520 ~ $privoxy-regression-test.pl
+2020-12-14 12:16:32: Asking Privoxy for the number of action files available ...
+2020-12-14 12:16:32: Gathering regression tests from 9 action file(s) delivered by Privoxy 3.0.30.
+2020-12-14 12:16:32: Executing regression tests ...
+2020-12-14 12:16:41: Ooops. Expected removal but: 'Referer: https://p.p/' is still there.
+2020-12-14 12:16:41: Failure for test 785. Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-block}'
+2020-12-14 12:16:41: Ooops. Got: 'Referer: https://p.p/' while expecting: 'Referer: http://p.p/'
+2020-12-14 12:16:41: Failure for test 791. Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-forge}'
+2020-12-14 12:16:44: Executed 1087 regression tests. Skipped 115. 1085 successes, 2 failures.
+# Repeat one of the failing tests and get a curl command to quickly reproduce the problem
+# without causing too much log noise.
+fk@t520 ~ $privoxy-regression-test.pl --test-number 785 --verbose --debug 4
+2020-12-14 12:17:55: Asking Privoxy for the number of action files available ...
+[...]
+2020-12-14 12:17:56: Executing regression tests ...
+2020-12-14 12:17:56: Executing: curl --include -H 'Proxy-Connection:' -H 'Connection: close' -s -S --user-agent 'Privoxy-Regression-Test 0.7.2' --max-time '5' --globoff -H 'X-Privoxy-Control: hide-referrer{conditional-block}' -H 'Referer: https://p.p/' http://p.p/show-request 2>&1
+2020-12-14 12:17:56: Ooops. Expected removal but: 'Referer: https://p.p/' is still there.
+2020-12-14 12:17:56: Failure for test 785 (0/13/5). Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-block}'
+2020-12-14 12:17:56: Executed 1 regression tests. Skipped 1201. 0 successes, 1 failures.
+ </programlisting>
+ <para>
+ Use the if the <command>--privoxy-address</command> option if the
+ http_proxy environment variable isn't configured and you don't want
+ to use the default (http://127.0.0.1:8118/).
+ </para>
+ </sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="fuzzing"><title>Fuzzing Privoxy</title>
<para>
<para>
The following programs are required to follow this process:
- <filename>ncftpput</filename> (ncftp), <filename>scp, ssh</filename> (ssh),
- <filename>gmake</filename> (GNU's version of make), autoconf, cvs.
+ <filename>ssh</filename>,
+ <filename>gmake</filename> (GNU's version of make), autoconf, git,
+ a web browser.
</para>
<sect2 id="versionnumbers">
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
- <application>Junkbuster</application>, and 3 will be the first stable
+ <application>Junkbuster</application>, and 3 is the first stable
<application>Privoxy</application> release.
</para>
</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]..master > /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>
(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>
+ <literal>https://www.privoxy.org/$(VERSION)/user-manual/</literal>. This
+ needs to be updated for each new release and is done with the
+ <quote>webserver</quote> target.
</para>
</listitem>
<listitem>
<para>
- Tag all files in CVS with the version number with
- <quote><command>cvs tag v_X_Y_Z</command></quote>.
+ Tag all files in Git with the version number with
+ <quote><command>git tag -s 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>
<programlisting>
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
+ git clone https://www.privoxy.org/git/privoxy.git
+ cd privoxy
+ git checkout v_X_Y_Z
</programlisting>
<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>
Also suggested: <filename>Developer Manual</filename>
(doc/webserver/developer-manual) and <filename>ChangeLog</filename>
(top-level directory). <filename>FAQ</filename> and the manuals are
- HTML docs. There are also text versions in
- <filename>doc/text/</filename> which could conceivably also be
- included.
+ HTML docs.
</para>
<para>
The documentation has been designed such that the manuals are linked
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:
</listitem>
<listitem>
<para>
- Other configuration files (<filename>default.action</filename> and
+ Other configuration files (<filename>default.action</filename>,
+ <filename>regression-tests.action</filename> and
<filename>default.filter</filename>) 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
<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 run:
+ packages" above). Then run from that directory:
</para>
<programlisting>
- cd current
autoheader && autoconf && ./configure
</programlisting>
<para>
<programlisting>
make tarball-dist
</programlisting>
- <para>
- To upload the package to Sourceforge, simply issue
- </para>
- <programlisting>
- make tarball-upload
-</programlisting>
- <para>
- Go to the displayed URL and release the file publicly on Sourceforge.
- For the change log field, use the relevant section of the
- <filename>ChangeLog</filename> file.
- </para>
</sect3>
- <sect3 id="newrelease-rpm"><title>SuSE, Conectiva or Red Hat RPM</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>
- In following text, replace <replaceable class="parameter">dist</replaceable>
- with either <quote>rh</quote> for Red Hat or <quote>suse</quote> for SuSE.
+ 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).
+ <!-- XXX ??? are we still basing releases off a tarball???
+ -->
</para>
<para>
- As the only exception to not changing anything after export from CVS,
- 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
- be reset to one if this is the first RPM for
- <replaceable class="parameter">dist</replaceable> which is built from version
- X.Y.Z. Check the
- <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">file
- list</ulink> if unsure. Else, it must be set to the highest already available RPM
- release number for that version plus one.
+ Then you can build the package. This is fully automated, and is
+ controlled by <filename>windows/GNUmakefile</filename>.
+ All you need to do is:
</para>
+ <programlisting>
+ cd windows
+ make
+</programlisting>
<para>
- Then run:
+ Now you can manually rename <filename>privoxy_setup.exe</filename> to
+ <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>
- cd current
- autoheader && autoconf && ./configure
+ <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>
- Then do
+ and upload the files to SourceForge.
</para>
- <programlisting>
- make <replaceable class="parameter">dist</replaceable>-dist
+
+ <para>
+ When releasing the package on SourceForge, use the release notes
+ and Change Log from the source tarball package.
+ </para>
+ </sect3>
+
+ <sect3 id="newrelease-debian"><title>Debian</title>
+ <para>
+ Using git-buildpackage we start with a clone of the last Debian version:
+ </para>
+ <programlisting>
+ gbp clone https://salsa.debian.org/debian/privoxy.git
+ cd privoxy
</programlisting>
<para>
- To upload the package to Sourceforge, simply issue
+ or if the repository is already there
</para>
- <programlisting>
- make <replaceable class="parameter">dist</replaceable>-upload <replaceable class="parameter">rpm_packagerev</replaceable>
+ <programlisting>
+ cd privoxy
+ gbp pull
</programlisting>
<para>
- where <replaceable class="parameter">rpm_packagerev</replaceable> 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.
+ Now import the newly released upstream tarball via debian/watch file:
</para>
- </sect3>
-
- <sect3 id="newrelease-os2"><title>OS/2</title>
+ <programlisting>
+ gbp import-orig --uscan
+</programlisting>
<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 OS/2 Setup module:
+ Next update all Debian quilt patches to the new version:
</para>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
+ <programlisting>
+ while quilt push; do quilt refresh; done
</programlisting>
<para>
- You will need a mix of development tools.
- The main compilation takes place with IBM Visual Age C++.
- Some ancillary work takes place with GNU tools, available from
- various sources like hobbes.nmsu.edu.
- Specificially, you will need <filename>autoheader</filename>,
- <filename>autoconf</filename> and <filename>sh</filename> tools.
- The packaging takes place with WarpIN, available from various sources, including
- its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
+ If some patch is no longer required (because it is already merged
+ upstream), it can be removed using
</para>
+ <programlisting>
+ quilt delete XX_patchname.patch
+ git rm debian/patches/XX_patchname.patch
+</programlisting>
<para>
- Change directory to the <filename>os2setup</filename> directory.
- Edit the os2build.cmd file to set the final executable filename.
- For example,
+ If the patch needs modification, you can apply, edit and update it with
</para>
- <programlisting>
- installExeName='privoxyos2_setup_X.Y.Z.exe'
+ <programlisting>
+ quilt push -f
+ quilt edit some_file
+ quilt refresh
</programlisting>
<para>
- Next, edit the <filename>IJB.wis</filename> file so the release number matches
- in the <filename>PACKAGEID</filename> section:
+ until
</para>
- PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
+ <programlisting>
+ while quilt push; do quilt refresh; done
</programlisting>
<para>
- You're now ready to build. Run:
+ succeeds. Then you can
</para>
- os2build
+ <programlisting>
+ quilt pop -a
</programlisting>
<para>
- You will find the WarpIN-installable executable in the
- <filename>./files</filename> directory. Upload this anonymously to
- <filename>uploads.sourceforge.net/incoming</filename>, create a release
- for it, and you're done. Use the release notes and Change Log from the
- source tarball package.
+ Now add a new entry to the debian/changelog representing the new
+ version:
</para>
- </sect3>
-
- <sect3 id="newrelease-solaris"><title>Solaris</title>
+ <programlisting>
+ dch -v &p-version;-1
+</programlisting>
<para>
- Login to Sourceforge's compilefarm via ssh:
+ and describe what you did before and don't forget to git commit all
+ changes.
</para>
- <programlisting>
- ssh cf.sourceforge.net
+ <para>
+ Now you can build the package on the local machine using
+ </para>
+ <programlisting>
+ gbp buildpackage -us -uc
</programlisting>
<para>
- Choose the right operating system (not the Debian one).
- When logged in, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ You should check for warnings using
</para>
- <programlisting>
- cd current
- autoheader && autoconf && ./configure
+ <programlisting>
+ lintian -iI ../build-area/privoxy_&p-version;-1_amd64.changes
</programlisting>
<para>
- Then run
+ Maybe rebuild the package in different defined cowbuilder environments
+ like
</para>
- gmake solaris-dist
+ <programlisting>
+ sudo cowbuilder --build --basepath /var/cache/pbuilder/base.cow ../build-area/privoxy_&p-version;-1.dsc
</programlisting>
<para>
- which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
- solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
- to manually upload the archive to Sourceforge's ftp server and release
- the file publicly. Use the release notes and Change Log from the
- source tarball package.
+ And try to run autopackage testing suite on the result:
+ </para>
+ <programlisting>
+ autopkgtest /var/cache/pbuilder/result/privoxy_&p-version;-1_amd64.changes -s -- schroot sid
+</programlisting>
+ <para>
+ Or just push the changes to salsa.debian.org, where a CI pipeline is
+ defined for the package, that builds and tests it.
+ </para>
+ <para>
+ If everything is okay, run cowbuilder with i386 and amd64 environments
+ for current Debian stable release and build
+ privoxy_&p-version;-1_i386.deb and privoxy_&p-version;-1_amd64.deb.
+ Then sign both files:
+ </para>
+ <programlisting>
+ gpg --detach-sign --armor privoxy_&p-version;-1_i386.deb
+ gpg --detach-sign --armor privoxy_&p-version;-1_amd64.deb
+</programlisting>
+ <para>
+ Create a README file containing the recent block from debian/changelog
+ and upload the two packages, the two signatures and the README to a
+ freshly created folder below
+ https://sourceforge.net/projects/ijbswa/files/Debian/
</para>
- </sect3>
- <sect3 id="newrelease-windows"><title>Windows</title>
+ <sect4 id="snapshot-debian"><title>Debian GIT Snapshot</title>
<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.
+ For building just a git snapshot build the following workflow may be
+ useful. First create a build environment, for this you may have to
+ run the following commands:
</para>
+ <programlisting>
+ sudo apt install build-essential devscripts
+ sudo apt-get build-dep privoxy
+</programlisting>
<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:
+ After this enter the checked out privoxy git tree and check that all
+ (new) build dependencies are met:
</para>
<programlisting>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
+ dpkg-checkbuilddeps
</programlisting>
<para>
- Then you can build the package. This is fully automated, and is
- controlled by <filename>winsetup/GNUmakefile</filename>.
- All you need to do is:
+ If something is missing, just add it using
</para>
<programlisting>
- cd winsetup
- make
+ sudo apt install foobar
</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
- and Change Log from the source tarball package.
+ Now you may update debian/changelog, especially the version number
+ using
</para>
- </sect3>
-
- <sect3 id="newrelease-debian"><title>Debian</title>
+ <programlisting>
+ dch
+</programlisting>
<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 add a log
- entry to <filename>debian/changelog</filename>, if it is not
- already there, for example by running:
+ and finally build the package:
</para>
- debchange -v &p-version;-&p-status;-1 "New upstream version"
+ <programlisting>
+ debuild -us -uc -b
</programlisting>
<para>
- Then, run:
+ If everything went okay, you may find the resulting Debian package in
+ the parent directory.
</para>
- <programlisting>
- dpkg-buildpackage -rfakeroot -us -uc -b
+ <para>
+ You may want to clean up the build tree using
+ </para>
+ <programlisting>
+ debian/rules clean
</programlisting>
<para>
- This will create
- <filename>../privoxy_&p-version;-&p-status;-1_i386.deb</filename>
- which can be uploaded. To upload the package to Sourceforge, simply
- issue
+ And maybe repair some artefacts using one or both of the following
+ commands:
</para>
- <programlisting>
- make debian-upload
+ <programlisting>
+ git reset --hard
+ git clean -fd
</programlisting>
+ </sect4>
</sect3>
<sect3 id="newrelease-macosx"><title>Mac OS X</title>
packages" above).
</para>
<para>
- There are three modules available in the CVS repository for use on Mac
+ There are three modules available in the CVS repository backups 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>
<sect4 id="OS-X-OSXPackageBuilder-module">
- <title>OSXPackageBuilder module</title>
+ <title>OSXPackageBuilder module (Documentation out of date)</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
</para>
</sect4>
<sect4 id="OS-X-osxsetup-module">
- <title>osxsetup module (DEPRECATED)</title>
+ <title>osxsetup module (DEPRECATED) (Documentation out of date)</title>
<para>
<emphasis>This module is deprecated since the installer it generates
places all Privoxy files in one folder in a non-standard location, and
</para>
</sect4>
<sect4 id="OS-X-macsetup-module">
- <title>macsetup module</title>
+ <title>macsetup module (Documentation out of date)</title>
<para>
The macsetup module is ideal if you wish to build and install Privoxy
from source on a single machine.
<title>Uploading and Releasing Your Package</title>
<para>
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:
- </para>
- <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>,
- 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
- of <literal>$VERSION ($CODE_STATUS)</literal>, e.g. <emphasis>&p-version;
- (beta)</emphasis>.
+ and go through the release steps. The upload
+ is done at
+ <ulink url="https://sourceforge.net/projects/ijbswa/upload/">SourceForge</ulink>
+ after logging in.
</para>
<para>
Now just follow the prompts. Be sure to add any appropriate Release
<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: "Announcing Privoxy X.Y.Z $CODE_STATUS". 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/projects/ijbswa/files/">
+ 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>
make webserver
</programlisting>
<para>
- This will do the upload to <ulink url="https://www.privoxy.org/">the
- webserver</ulink> (www.privoxy.org) and ensure all files and directories
- there are group writable.
+ This will do the upload to the SourceForge webserver (which is manually
+ syncronized with <ulink url="https://www.privoxy.org/">www.privoxy.org</ulink>)
+ and ensure all files and directories there are group writable.
</para>
<para>
Please do <emphasis>NOT</emphasis> use any other means of transferring
projects / privoxy.git / blobdiff