X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=b56d6beeafe381b06b6f06d240887e8a582eb3f1;hp=18115067333461fd6c33c9f9fcbcf9b73a1b6163;hb=3faadc6490219a0db4d617918145d540e4affb98;hpb=08f3b18a3cb223cad6e3925ba1021206fd59d37e diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 18115067..b56d6bee 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -192,6 +192,56 @@ Hal. Before pushing stuff, please rebase it on a current master so we get an uncomplicated commit history. Avoid merges where possible. + + Here's an example git sesssion that should result in a merge-free history: + + +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. + - Privoxy Custom Entities + Privoxy Custom Entities Privoxy documentation is using a number of customized entities to facilitate @@ -1972,6 +2022,48 @@ Install the rpm. Any error messages? + + Testing with <application>Privoxy-Regression-Test</application> + + If you compiled, packaged or merely installed Privoxy, it is recommended to run + Privoxy-Regression-Test to verify that at least + the tested parts of Privoxy are working as expected. + + + This is actually pretty easy. For details, please see + perldoc privoxy-regression-test.pl. + + + Here is an example of what Privoxy-Regression-Test can do for you: + + +# 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. + + + Use the if the --privoxy-address option if the + http_proxy environment variable isn't configured. + + + Fuzzing Privoxy @@ -2203,7 +2295,7 @@ for-privoxy-version=3.0.11 $ 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 @@ -2274,14 +2366,14 @@ for-privoxy-version=3.0.11 link from the main page since we need to keep manuals for various versions available). The CGI pages will link to something like https://www.privoxy.org/$(VERSION)/user-manual/. 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. + needs to be updated for each new release and is done with the + webserver target. Tag all files in Git with the version number with - git tag v_X_Y_Z. + git tag -s v_X_Y_Z. Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. @@ -2398,9 +2490,7 @@ for-privoxy-version=3.0.11 Also suggested: Developer Manual (doc/webserver/developer-manual) and ChangeLog (top-level directory). FAQ and the manuals are - HTML docs. There are also text versions in - doc/text/ which could conceivably also be - included. + HTML docs. The documentation has been designed such that the manuals are linked @@ -2430,7 +2520,8 @@ for-privoxy-version=3.0.11 - Other configuration files (default.action and + Other configuration files (default.action, + regression-tests.action and default.filter) 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 @@ -2465,10 +2556,9 @@ for-privoxy-version=3.0.11 First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing - packages" above). Then run: + packages" above). Then run from that directory: - cd current autoheader && autoconf && ./configure @@ -2477,17 +2567,6 @@ for-privoxy-version=3.0.11 make tarball-dist - - To upload the package to Sourceforge, simply issue - - - make tarball-upload - - - Go to the displayed URL and release the file publicly on Sourceforge. - For the change log field, use the relevant section of the - ChangeLog file. - SuSE, Conectiva or Red Hat RPM @@ -2525,18 +2604,6 @@ for-privoxy-version=3.0.11 make dist-dist - - To upload the package to Sourceforge, simply issue - - - make dist-upload rpm_packagerev - - - where rpm_packagerev 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. - Solaris @@ -2639,12 +2706,8 @@ for-privoxy-version=3.0.11 This will create ../privoxy_&p-version;-&p-status;-1_i386.deb - which can be uploaded. To upload the package to Sourceforge, simply - issue + which can be uploaded. - - make debian-upload - Mac OS X @@ -2759,38 +2822,10 @@ for-privoxy-version=3.0.11 Uploading and Releasing Your Package 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: - - - - - Upload to: ftp://upload.sourceforge.net/incoming - - - - - user: anonymous - - - - - password: ijbswa-developers@lists.sourceforge.net - - - - - Or use the make targets as described above. - - - Once this done go to - - https://sourceforge.net/project/admin/editpackages.php?group_id=11118, - making sure you are logged in. Find your target platform in the - second column, and click Add Release. You will - then need to create a new release for your package, using the format - of $VERSION ($CODE_STATUS), e.g. &p-version; - (beta). + and go through the release steps. The upload + is done at + SourceForge + after logging in. Now just follow the prompts. Be sure to add any appropriate Release