X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=6a0e72e8e639ac0a47b310756e0a265626ac9569;hb=e41d3e9bb9ba6637826a66937a694c8efae10fad;hp=6b1333fb162bce92497c882ba7292ffe4850a1e6;hpb=fdbc2647e7be299218036c36c9179b6f5adb2349;p=privoxy.git
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 6b1333fb..6a0e72e8 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-2018 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2020 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
@@ -39,7 +39,7 @@
Copyright
- &my-copy; 2001-2018 by
+ &my-copy; 2001-2020 by
Privoxy Developers
@@ -133,8 +133,8 @@ Hal.
can be sent to the list for review too.
- You will also need to have a git package installed, which will
- entail having ssh installed as well, in order to access the git repository.
+ You will also need to have a git package installed,
+ in order to access the git repository.
Having the GNU build tools is also going to be important (particularly,
autoconf and gmake).
@@ -158,10 +158,16 @@ Hal.
Access to Git
The project's Git repository is hosted at the
- Privoxy site.
- The Git repository URL is
- ssh://git@git.privoxy.org:23/git/privoxy.git,
- the central repository is called privoxy, and the
+ Privoxy website.
+ For Privoxy team members with push privileges the Git repository URL is
+ ssh://git@git.privoxy.org:23/git/privoxy.git.
+
+
+ Contributors without push privileges can
+ git clone https://www.privoxy.org/git/privoxy.git
.
+
+
+ The central repository is called privoxy, and the
source branch is called master. Subfolders exist
within the project for target-dependent build and packaging tools, each
including the name of the target operating system in their name (e.g.
@@ -518,13 +524,13 @@ Hal.
<para>
Some text goes here.
</para>
-
+
Tags marking individual words, or few words, should be in-line:
Just to <emphasis>emphasize</emphasis>, some text goes here.
-
+
@@ -541,7 +547,7 @@ Hal.
</para>
</itemizedlist>
</para>
-
+
This makes it easier to find the text amongst the tags ;-)
@@ -651,6 +657,7 @@ Hal.
the finished doc at that point.
+
Commonly used internal entities
:
@@ -2069,6 +2076,7 @@ $ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.
+
Y, the version minor, represents the branch within the major version.
At any point in time, there are two branches being maintained:
The stable branch, with an even minor, say, 2N, in which no functionality is
@@ -2086,13 +2094,15 @@ $ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.
Z, the point or sub version, represents a release of the software within a branch.
- It is therefore incremented immediately before each code freeze.
+ It is therefore incremented immediately after each software release.
+
The point version is reset to zero when the minor changes.
@@ -2135,32 +2145,39 @@ $ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.
- Before the Release: Freeze
+ Before the Release
The following must be done by one of the
developers prior to each new release.
-
-
-
+
+
+
Make sure that everybody who has worked on the code in the last
couple of days has had a chance to yell no!
in case
they have pending changes/fixes in their pipelines. Announce the
freeze so that nobody will interfere with last minute changes.
-
+
- Increment the version number (point from odd to even in development
- branches!) in configure.in and update the code
- status (CODE_STATUS="xxx") to one of "alpha", "beta" or "stable".
- Rebuild configure and GNUMakefile to make sure the updated values are
- being used.
+ Update the code status (CODE_STATUS="xxx") in configure.in to one of
+ "alpha", "beta" or "stable".
- Use the dok-release target to update the sgml documentation source files.
+ Rebuild configure and GNUMakefile to make sure the updated values are being used.
+
+
+
+$ autoheader && autoconf # rebuild configure
+$ ./configure # rebuild GNUmakefile
+
+
+
+
+ make dok-release to update the sgml documentation source files.
@@ -2178,15 +2195,70 @@ for-privoxy-version=3.0.11
- All documentation should be rebuild after the version bump.
+ 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
+
+
+ Edit /tmp/change.log to remove trivial
+ changes and group the changes under general headings like:
+
+
+- Bug fixes:
+- Action file improvements:
+- Filter file improvements:
+- General improvements:
+- Documentation improvements:
+- Build system improvements:
+- Code cleanups:
+- Privoxy-Log-Parser:
+- Privoxy-Regression-Test:
+
+
+ Add the contents of /tmp/change.log to the
+ start of ChangeLog and re-create
+ doc/source/changelog.sgml:
+
+
+ $ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
+
+
+
+
+ All developers should look at the ChangeLog and
+ make sure noteworthy changes are referenced.
+
+
+
+
+ All documentation should be rebuilt:
+
+ $ 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
rather obscure processing tools. config,
the man page (and the html version of the man page)
fall in this category. README, the man page, AUTHORS, and config
should all also be committed to Git for other packagers. The
- formal docs should be uploaded to the webserver. See the
- Section "Updating the webserver" in this manual for details.
+ formal docs should be uploaded to the webserver. See the section
+ "Updating the webserver"
+ in this manual for details.
+
+
+
+
+ Commit all files that were changed in the above steps!
@@ -2203,31 +2275,13 @@ for-privoxy-version=3.0.11
target for this at this time!!! It needs to be done manually.
-
-
- All developers should look at the ChangeLog and
- make sure noteworthy changes are referenced.
-
-
-
-
- Commit all files that were changed in the above steps!
-
-
Tag all files in Git with the version number with
- cvs tag v_X_Y_Z
.
+ git tag v_X_Y_Z
.
Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
-
-
- If the release was in a development branch, increase the point version
- from even to odd (X.Y.(Z+1)) again in configure.in and
- commit your change.
-
-
On the webserver, copy the user manual to a new top-level directory
@@ -2258,8 +2312,9 @@ for-privoxy-version=3.0.11
mkdir dist # delete or choose different name if it already exists
cd dist
- cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ git clone https://www.privoxy.org/git/privoxy.git
+ cd privoxy
+ git checkout v_X_Y_Z
@@ -2495,7 +2550,7 @@ for-privoxy-version=3.0.11
The main compilation takes place with IBM Visual Age C++.
Some ancillary work takes place with GNU tools, available from
various sources like hobbes.nmsu.edu.
- Specificially, you will need autoheader,
+ Specifically, you will need autoheader,
autoconf and sh tools.
The packaging takes place with WarpIN, available from various sources, including
its home page: xworkplace.
@@ -2562,33 +2617,50 @@ for-privoxy-version=3.0.11
- Windows
+ Windows
+
- Use the
- Cygwin Time Machine to install the last 1.5 version of Cygwin.
- Run the following commands from within the Cygwin 1.5 bash shell.
+ 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). Then get the Windows setup module:
+ packages" above).
+
-
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
-
Then you can build the package. This is fully automated, and is
- controlled by winsetup/GNUmakefile.
+ controlled by windows/GNUmakefile.
All you need to do is:
- cd winsetup
+ cd windows
make
Now you can manually rename privoxy_setup.exe to
- privoxy_setup_X_Y_Z.exe, and upload it to
- SourceForge. When releasing the package on SourceForge, use the release notes
+ 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,
+
+
+ $ gpg --armor --detach --sign privoxy_setup_X.Y.Z.exe
+ $ gpg --armor --detach --sign privoxy_X.Y.Z.zip
+
+
+ and upload the files to SourceForge.
+
+
+
+ When releasing the package on SourceForge, use the release notes
and Change Log from the source tarball package.
@@ -2736,30 +2808,30 @@ for-privoxy-version=3.0.11
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
-
-
-
+
+
+
+ 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,
+ 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
@@ -2789,15 +2861,44 @@ for-privoxy-version=3.0.11
After the Release
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
+ send an email to the
+ announce mailing
+ list, Subject: "Version X.Y.Z available for download". Be sure to
include the
- download
- location, the release notes and the Changelog. Also, post an
+
+ download location, the release notes and the Changelog. Also, post an
updated News item on the project page Sourceforge, and update the Home
page and docs linked from the Home page (see below). Other news sites
and release oriented sites, such as Freshmeat, should also be notified.
+
+ Then update the source code for the next version to be released:
+
+
+
+
+ Increment the version number and change the code status to "UNRELEASED"
+ in configure.in
+
+
+
+
+ Rebuild configure (autoheader && autoconf
)
+ and GNUMakefile (./configure
)
+
+
+
+
+ make dok-release
to update the sgml documentation source files.
+
+
+
+
+ Commit all your changes.
+
+
+
+