X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=e8b472f182ac14f86cec9ad21b979d93240d5718;hb=4697cf05fcd27c0c559477f66d82784ebcb60b42;hp=f384cbf2f99eb5690e5382e1a4f10eb89bb583ae;hpb=c79d5a23e325b6408801445794b8ca5885105e65;p=privoxy.git
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index f384cbf2..e8b472f1 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -5,7 +5,7 @@
-
+
@@ -19,7 +19,7 @@
Purpose : developer manual
- Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -39,7 +39,7 @@
Copyright
- &my-copy; 2001-2020 by
+ &my-copy; 2001-2021 by
Privoxy Developers
@@ -390,7 +390,7 @@ Successfully rebased and updated refs/heads/local-branch.
course this, the developer-manual in this format.
The README, AUTHORS,
INSTALL,
- privoxy.1 (man page), and
+ privoxy.8 (man page), and
config files are also now maintained as Docbook
SGML. These files, when built, in the top-level source directory are
generated files! Also, the Privoxy index.html (and a
@@ -2057,10 +2057,11 @@ fk@t520 ~ $privoxy-regression-test.pl --test-number 785 --verbose --debug 4
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.
+ http_proxy environment variable isn't configured and you don't want
+ to use the default (http://127.0.0.1:8118/).
@@ -2256,7 +2257,7 @@ $ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.
- Update the code status (CODE_STATUS="xxx") in configure.in to one of
+ Update the code status (CODE_STATUS="xxx") in configure.in to one of
"alpha", "beta" or "stable".
@@ -2279,7 +2280,7 @@ $ ./configure # rebuild GNUmakefile
If action file processing has changed and is not backward-compatible,
make sure the "for-privoxy-version=x.y.z" minimum version number in
- default.action.master has been updated:
+ default.action.master has been updated:
{{settings}}
@@ -2293,12 +2294,12 @@ for-privoxy-version=3.0.11
Create the change log:
- $ git tag
- # to see the tags
- $ git log [last release tag]..HEAD > /tmp/log
- # get the commit log since the last release
- $ utils/makeChangeLog /tmp/log > /tmp/change.log
- # reformat the commit log
+$ 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
Edit /tmp/change.log to remove trivial
@@ -2321,7 +2322,7 @@ for-privoxy-version=3.0.11
doc/source/changelog.sgml:
- $ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
+$ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
@@ -2330,15 +2331,20 @@ for-privoxy-version=3.0.11
make sure noteworthy changes are referenced.
+
+
+ Update the announcement at doc/webserver/announce.txt.
+
+
All documentation should be rebuilt:
- $ make man
- $ make dok
- $ make dok-man
- $ make dok-tidy
- $ make config-file
+$ make man
+$ make dok
+$ make dok-man
+$ make dok-tidy
+$ make config-file
Finished docs should be then be committed to Git (for those
without the ability to build these). Some docs may require
@@ -2366,17 +2372,23 @@ 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.
+
+
+ Push the tag to the remote with
+ git push origin v_X_Y_Z
.
+
+
On the webserver, copy the user manual to a new top-level directory
@@ -2405,11 +2417,11 @@ for-privoxy-version=3.0.11
- mkdir dist # delete or choose different name if it already exists
- cd dist
- git clone https://www.privoxy.org/git/privoxy.git
- cd privoxy
- git checkout v_X_Y_Z
+mkdir dist # delete or choose different name if it already exists
+cd dist
+git clone https://www.privoxy.org/git/privoxy.git
+cd privoxy
+git checkout v_X_Y_Z
@@ -2490,9 +2502,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
@@ -2522,7 +2532,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
@@ -2557,286 +2568,277 @@ 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
+autoheader && autoconf && ./configure
Then do:
- make tarball-dist
-
-
- To upload the package to Sourceforge, simply issue
-
-
- make tarball-upload
+make tarball-dist
-
- 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
+ Windows
+
- In following text, replace dist
- with either rh
for Red Hat or suse
for SuSE.
+ Note that the docbook generated files might need some hand editing,
+ so the Windows build makefile does not rebuild the docs.
+
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.
+ Check that you have the current versions of the
+
+ NSIS installer,
+ PCRE library,
+ MBED TLS library,
+
+ Brotli library,
+ and that the MAKENSIS evar in
+ windows/GNUMakefile
+ points to the NSIS installer program. (See the
+
+ Building from Source / Windows
+ section of the User Manual for details.)
+
- Then run:
+ Then you can build the package. This is fully automated, and is
+ controlled by windows/GNUmakefile.
+ All you need to do is:
-
- cd current
- autoheader && autoconf && ./configure
+
+cd windows
+make
- Then do
+ Now you can manually rename privoxy_setup.exe to
+ privoxy_setup_X.Y.Z.exe, and the build
+ directory to privoxy_X.Y.Z.
+ Create a .zip file of the newly renamed privoxy_X.Y.Z directory,
+ GPG sign the installer and zip file,
-
- make dist-dist
+
+gpg --armor --detach --sign privoxy_setup_X.Y.Z.exe
+gpg --armor --detach --sign privoxy_X.Y.Z.zip
- To upload the package to Sourceforge, simply issue
+ and upload the files to SourceForge.
-
- 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.
+ When releasing the package on SourceForge, use the release notes
+ and Change Log from the source tarball package.
- Solaris
+ Debian
- Login to Sourceforge's compilefarm via ssh:
+ Using git-buildpackage we start with a clone of the last Debian version:
-
- ssh cf.sourceforge.net
+
+gbp clone https://salsa.debian.org/debian/privoxy.git
+cd privoxy
- 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:
+ or if the repository is already there
-
- cd current
- autoheader && autoconf && ./configure
+
+cd privoxy
+gbp pull
- Then run
+ Now import the newly released upstream tarball via debian/watch file:
-
- gmake solaris-dist
+
+gbp import-orig --uscan
- 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.
+ Next update all Debian quilt patches to the new version:
-
-
- Windows
-
+
+while quilt push; do quilt refresh; done
+
- Note that the docbook generated files might need some hand editing,
- so the Windows build makefile does not rebuild the docs.
+ 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
+
- First, make sure that you have freshly exported the right
- version into an empty directory. (See "Building and releasing
- packages" above).
-
+ If the patch needs modification, you can apply, edit and update it with
+
+quilt push -f
+quilt edit some_file
+quilt refresh
+
- Then you can build the package. This is fully automated, and is
- controlled by windows/GNUmakefile.
- All you need to do is:
+ until
- cd windows
- make
+while quilt push; do quilt refresh; done
- Now you can manually rename privoxy_setup.exe to
- privoxy_setup_X.Y.Z.exe, and the build
- directory to privoxy_X.Y.Z.
- Create a .zip file of the newly renamed privoxy_X.Y.Z directory,
- GPG sign the installer and zip file,
+ succeeds. Then you can
- $ gpg --armor --detach --sign privoxy_setup_X.Y.Z.exe
- $ gpg --armor --detach --sign privoxy_X.Y.Z.zip
+quilt pop -a
- and upload the files to SourceForge.
+ Now add a new entry to the debian/changelog representing the new
+ version:
-
+
+dch -v &p-version;-1
+
- When releasing the package on SourceForge, use the release notes
- and Change Log from the source tarball package.
+ 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/
-
- Debian
+ Debian GIT Snapshot
- First, make sure that you have freshly exported the
- 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:
+ 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:
-
- debchange -v &p-version;-&p-status;-1 "New upstream version"
+
+sudo apt install build-essential devscripts
+sudo apt-get build-dep privoxy
- Then, run:
+ After this enter the checked out privoxy git tree and check that all
+ (new) build dependencies are met:
-
- dpkg-buildpackage -rfakeroot -us -uc -b
+
+dpkg-checkbuilddeps
- This will create
- ../privoxy_&p-version;-&p-status;-1_i386.deb
- which can be uploaded. To upload the package to Sourceforge, simply
- issue
+ If something is missing, just add it using
-
- make debian-upload
+
+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
+ macOS / OS X
First, make sure that you have freshly exported the right
version into an empty directory. (See "Building and releasing
packages" above).
- 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).
+ The OSXPackageBuilder module can generate OS X installer packages
+ supporting all Macs running OS X 10.4 and above. Obtain it from Git as
+ follows into a folder parallel to the exported privoxy source:
-
- OSXPackageBuilder module (Documentation out of date)
-
- The OSXPackageBuilder module generates OS X installer packages
- 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:
-
-
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
-
-
- The module contains complete instructions on its usage in the file
- OS X Package Builder HOWTO.txt.
-
-
- Once the package(s) have been generated, you can then upload them
- directly to the Files section of the Sourceforge project in the
- Macintosh (OS X) folder. Each new version release of Privoxy should
- have a new subfolder created in which to store its files. Please
- ensure that the folder contains a readme file that makes it clear
- which package is for whichversion of OS X.
-
-
-
- osxsetup module (DEPRECATED) (Documentation out of date)
-
- 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.
-
-
- Check out the module from CVS as follows into a folder parallel to the
- exported privoxy source:
-
-
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
-
-
- Then run:
-
-
- cd osxsetup
- build
-
-
- This will run autoheader, autoconf
- and configure as well as make.
- Finally, it will copy over the necessary files to the ./osxsetup/files
- directory for further processing by PackageMaker.
-
-
- Bring up PackageMaker with the PrivoxyPackage.pmsp definition file,
- modify the package name to match the release, and hit the "Create
- package" button. If you specify ./Privoxy.pkg as the output package
- name, you can then create the distributable zip file with the command:
-
-
- zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
-
-
- You can then upload this file directly to the Files section of the
- Sourceforge project in the Macintosh (OS X) folder. Each new version
- release of Privoxy should have a new subfolder created in which to
- store its files.
- Please ensure that the folder contains a readme file that makes it
- clear which version(s) of OS X the package supports.
-
-
-
- macsetup module (Documentation out of date)
-
- The macsetup module is ideal if you wish to build and install Privoxy
- from source on a single machine.
-
-
- Check out the module from CVS as follows into a folder parallel to the
- exported privoxy source:
-
-
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup
+
+git clone ssh://git@git.privoxy.org:23/git/OSXPackageBuilder.git
-
- The module contains complete instructions on its usage in its
- README file. The end result will be the
- exported version of Privoxy installed on the build machine.
-
-
+
+ The module contains complete instructions on its usage in the file
+ OS X Package Builder HOWTO.txt.
+
+
+ Once the package(s) have been generated, you can then upload them
+ directly to the Files section of the Sourceforge project in the
+ Macintosh (OS X) folder. Each new version release of Privoxy should
+ have a new subfolder created in which to store its files. Please
+ ensure that the folder contains a readme file that makes it clear
+ which package is for which version of OS X.
+
FreeBSD
@@ -2851,38 +2853,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
@@ -2909,7 +2883,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
@@ -2962,7 +2936,7 @@ for-privoxy-version=3.0.11
SGML files, do:
- make dok
+make dok && make dok-tidy
That will generate doc/webserver/user-manual,
@@ -2987,7 +2961,7 @@ for-privoxy-version=3.0.11
If these are docs in the stable branch, then do:
- make webserver
+make webserver
This will do the upload to the SourceForge webserver (which is manually