X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=73b94ea9f60e46121df45f5d13fea62fbe568406;hp=2c32912e68657c321ab208e72832eae9d6ea3ba4;hb=e7bedf5f2879b7870a5298c1a23d9bd455d33188;hpb=0ceccf09851cc072eea19e2d675d624ca31ed962

diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 2c32912e..73b94ea9 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -188,6 +188,60 @@ Hal.
        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.
@@ -266,7 +320,9 @@ Hal.
             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>
@@ -380,7 +436,7 @@ Hal.
      <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
@@ -611,7 +667,7 @@ Hal.
 
  <!--   ~~~~~       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
@@ -1966,6 +2022,48 @@ Install the rpm. Any error messages?
     </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>
@@ -2197,7 +2295,7 @@ for-privoxy-version=3.0.11
        <programlisting>
   $ git tag
   #   to see the tags
-  $ git log [last release tag]..HEAD &gt; /tmp/log
+  $ git log [last release tag]..master &gt; /tmp/log
   #   get the commit log since the last release
   $ utils/makeChangeLog /tmp/log &gt; /tmp/change.log
   #   reformat the commit log
@@ -2275,7 +2373,7 @@ for-privoxy-version=3.0.11
       <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>