X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=79e0a7e02350f3a54d00ace8bd9eeaefda232b29;hp=43bf7be2c5e8431bc05bd91874f149f66d262898;hb=34a6a841e529579e2be4457ea0d4cb1befbc840a;hpb=4350ad82876c330253c061713441b69fe0108d2b;ds=sidebyside
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 43bf7be2..79e0a7e0 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
@@ -1970,6 +2022,49 @@ Install the rpm. Any error messages?
+
+ Testing with Privoxy-Regression-Test
+
+ 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 and you don't want
+ to use the default (http://127.0.0.1:8118/).
+
+
+
Fuzzing Privoxy
@@ -2201,7 +2296,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
@@ -2272,14 +2367,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.
@@ -2396,9 +2491,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
@@ -2428,7 +2521,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
@@ -2463,10 +2557,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
@@ -2475,98 +2568,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
-
- In following text, replace dist
- with either rh
for Red Hat or suse
for SuSE.
-
-
- First, make sure that you have freshly exported the right
- version into an empty directory. (See "Building and releasing
- packages" above).
-
-
- As the only exception to not changing anything after export from Git,
- now examine the file privoxy-dist.spec
- 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
- dist which is built from version
- X.Y.Z. Check the
- file
- list if unsure. Else, it must be set to the highest already available RPM
- release number for that version plus one.
-
-
- Then run:
-
-
- cd current
- autoheader && autoconf && ./configure
-
-
- Then do
-
-
- 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
-
- Login to Sourceforge's compilefarm via ssh:
-
-
- ssh cf.sourceforge.net
-
-
- Choose the right operating system (not the Debian one).
- When logged in, make sure that you have freshly exported the right
- version into an empty directory. (See "Building and releasing
- packages" above). Then run:
-
-
- cd current
- autoheader && autoconf && ./configure
-
-
- Then run
-
-
- gmake solaris-dist
-
-
- which creates a gzip'ed tar archive. Sadly, you cannot use make
- solaris-upload 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.
-
Windows
@@ -2623,13 +2624,13 @@ for-privoxy-version=3.0.11
right version into an empty directory. (See
"Building and releasing packages" above). Then add a log
entry to debian/changelog, if it is not
- already there, for example by running:
+ already there, for example by running (from the debian directory):
debchange -v &p-version;-&p-status;-1 "New upstream version"
- Then, run:
+ Then, run (from the root directory):
dpkg-buildpackage -rfakeroot -us -uc -b
@@ -2637,12 +2638,172 @@ 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
-
+
+ Using git-buildpackage we start with a clone of the last Debian version:
+
+
+ gbp clone https://salsa.debian.org/debian/privoxy.git
+ cd privoxy
+
+
+ or if the repository is already there
+
+
+ cd privoxy
+ gbp pull
+
+
+ Now import the newly released upstream tarball via debian/watch file:
+
+
+ gbp import-orig --uscan
+
+
+ Next update all Debian quilt patches to the new version:
+
+
+ while quilt push; do quilt refresh; done
+
+
+ If some patch is no longer required (because it is already merged
+ upstream), it can be removed using
+
+
+ quilt delete XX_patchname.patch
+ git rm debian/patches/XX_patchname.patch
+
+
+ If the patch needs modification, you can apply, edit and update it with
+
+
+ quilt push -f
+ quilt edit some_file
+ quilt refresh
+
+
+ until
+
+
+ while quilt push; do quilt refresh; done
+
+
+ succeeds. Then you can
+
+
+ quilt pop -a
+
+
+ Now add a new entry to the debian/changelog representing the new
+ version:
+
+
+ dch -v &p-version;-1
+
+
+ and describe what you did before and don't forget to git commit all
+ changes.
+
+
+ Now you can build the package on the local machine using
+
+
+ gbp buildpackage -us -uc
+
+
+ You should check for warnings using
+
+
+ lintian -iI ../build-area/privoxy_&p-version;-1_amd64.changes
+
+
+ Maybe rebuild the package in different defined cowbuilder environments
+ like
+
+
+ sudo cowbuilder --build --basepath /var/cache/pbuilder/base.cow ../build-area/privoxy_&p-version;-1.dsc
+
+
+ And try to run autopackage testing suite on the result:
+
+
+ autopkgtest /var/cache/pbuilder/result/privoxy_&p-version;-1_amd64.changes -s -- schroot sid
+
+
+ Or just push the changes to salsa.debian.org, where a CI pipeline is
+ defined for the package, that builds and tests it.
+
+
+ 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:
+
+
+ gpg --detach-sign --armor privoxy_&p-version;-1_i386.deb
+ gpg --detach-sign --armor privoxy_&p-version;-1_amd64.deb
+
+
+ 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/
+
+
+ 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:
+
+
+ sudo apt install build-essential devscripts
+ sudo apt-get build-dep privoxy
+
+
+ After this enter the checked out privoxy git tree and check that all
+ (new) build dependencies are met:
+
+
+ dpkg-checkbuilddeps
+
+
+ If something is missing, just add it using
+
+
+ sudo apt install foobar
+
+
+ Now you may update debian/changelog, especially the version number
+ using
+
+
+ dch
+
+
+ and finally build the package:
+
+
+ debuild -us -uc -b
+
+
+ If everything went okay, you may find the resulting Debian package in
+ the parent directory.
+
+
+ You may want to clean up the build tree using
+
+
+ debian/rules clean
+
+
+ And maybe repair some artefacts using one or both of the following
+ commands:
+
+
+ git reset --hard
+ git clean -fd
+
+
Mac OS X
@@ -2757,38 +2918,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
@@ -2815,7 +2948,7 @@ for-privoxy-version=3.0.11
When all (or: most of the) packages have been uploaded and made available,
send an email to the
announce mailing
- list, Subject: "Version X.Y.Z available for download". Be sure to
+ list, Subject: "Announcing Privoxy X.Y.Z $CODE_STATUS". Be sure to
include the
download location, the release notes and the Changelog. Also, post an