<!entity p-intro SYSTEM "privoxy.sgml">
<!entity history SYSTEM "history.sgml">
<!entity seealso SYSTEM "seealso.sgml">
-<!entity p-version "3.0.29">
-<!entity p-status "stable">
-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity p-version "3.0.30">
+<!entity p-status "UNRELEASED">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
<!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml -->
-->
<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,
<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>.
+ 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>
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.
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/p/ijbswa/patches/">patch
- tracker</ulink> instead.
+ tracker</ulink> or the <ulink
+ url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel mailing list</ulink>
+ instead.
</para>
</listitem>
</itemizedlist>
<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
<!-- ~~~~~ 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
</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.
+ </para>
+ </sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="fuzzing"><title>Fuzzing Privoxy</title>
<para>
<programlisting>
$ git tag
# to see the tags
- $ git log [last release tag]..HEAD > /tmp/log
+ $ 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
(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
+ <literal>https://www.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>
<para>
Tag all files in Git with the version number with
- <quote><command>git tag v_X_Y_Z</command></quote>.
+ <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>
packages" above).
</para>
<para>
- There are three modules available in the Git 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 Git as
+ supporting all Macs running OS X 10.4 and above. Obtain it from CVS as
follows into a folder parallel to the exported privoxy source:
</para>
<programlisting>
</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
supports only Intel Macs running OS X 10.6 or higher.</emphasis>
</para>
<para>
- Check out the module from Git as follows into a folder parallel to the
+ Check out the module from CVS as follows into a folder parallel to the
exported privoxy source:
</para>
<programlisting>
</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.
</para>
<para>
- Check out the module from Git as follows into a folder parallel to the
+ Check out the module from CVS as follows into a folder parallel to the
exported privoxy source:
</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