Releasing a new version

Prev 8. Releasing a new version6. Releasing a New Version

To minimize trouble with distribution contents, webpage - errors and the like, we strongly encourage you - to follow this section if you prepare a new release of - code or new pages on the webserver. +> When we release versions of Privoxy, + our work leaves our cozy secret lab and has to work in the cold + RealWorld[tm]. Once it is released, there is no way to call it + back, so it is very important that great care is taken to ensure + that everything runs fine, and not to introduce problems in the + very last minute. +

So when releasing a new version, please adhere exactly to the + procedure outlined in this chapter.

The following programs are required to follow this process: @@ -85,29 +101,162 @@ CLASS="FILENAME" >ncftpput (ncftp), scpscp, ssh (ssh), -gmake (GNU's version of make), autoconf, cvs, ???. +> (GNU's version of make), autoconf, cvs.

6.1. Version numbers

First you need to determine which version number the release will have. + Privoxy version numbers consist of three numbers, + separated by dots, like in X.Y.Z (e.g. 3.0.0), where: +

Replace X, Y and Z with the actual version number (X = major, Y = minor, Z = point): +> X, the version major, is rarely ever changed. It is increased by one if + turning a development branch into stable substantially changes the functionality, + user interface or configuration syntax. Majors 1 and 2 were + Junkbuster, and 3 will be the first stable + Privoxy release. +
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 + being added and only bug-fixes are made, and 2N+1, the development branch, in + which the further development of Privoxy takes + place. + This enables us to turn the code upside down and inside out, while at the same time + providing and maintaining a stable version. + The minor is reset to zero (and one) when the major is incremented. When a development + branch has matured to the point where it can be turned into stable, the old stable branch + 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the + new stable branch 2N+2, and a new development branch 2N+3 is opened. +
Z, the point or sub version, represents a release of the software within a branch. + It is therefore incremented immediately before each code freeze. + In development branches, only the even point versions correspond to actual releases, + while the odd ones denote the evolving state of the sources on CVS in between. + It follows that Z is odd on CVS in development branches most of the time. There, it gets + increased to an even number immediately before a code freeze, and is increased to an odd + number again immediately thereafter. + This ensures that builds from CVS snapshots are easily distinguished from released versions. + The point version is reset to zero when the minor changes. +
Stable branches work a little differently, since there should be + little to no development happening in such branches. Remember, + only bugfixes, which presumably should have had some testing + before being committed. Stable branches will then have their + version reported as 0.0.0, during that period + between releases when changes are being added. This is to denote + that this code is not for release. Then + as the release nears, the version is bumped according: e.g. + 3.0.1 -> 0.0.0 -> 3.0.2. +

In summary, the main CVS trunk is the development branch where new + features are being worked on for the next stable series. This should + almost always be where the most activity takes place. There is always at + least one stable branch from the trunk, e.g now it is + 3.0, which is only used to release stable versions. + Once the initial *.0 release of the stable branch has been done, then as a + rule, only bugfixes that have had prior testing should be committed to + the stable branch. Once there are enough bugfixes to justify a new + release, the version of this branch is again incremented Example: 3.0.0 + -> 3.0.1 -> 3.0.2, etc are all stable releases from within the stable + branch. 3.1.x is currently the main trunk, and where work on 3.2.x is + taking place. If any questions, please post to the devel list + before committing to a stable branch! +

Developers should remember too that if they commit a bugfix to the stable + branch, this will more than likely require a separate submission to the + main trunk, since these are separate development trees within CVS. If you + are working on both, then this would require at least two separate check + outs (i.e main trunk, and the stable release branch, + which is v_3_0_branch at the moment). +

8.1. Before the Release6.2. Before the Release: Freeze

The following The following must be done by one of the developers prior to each new release.

"no!" in case - they have pending changes/fixes in their pipelines. + they have pending changes/fixes in their pipelines. Announce the + freeze so that nobody will interfere with last minute changes.

Increment the version number in Increment the version number (point from odd to even in development + branches!) in configure.in in - CVS. Also, inrease or reset the RPM release number in - configure.in as appropriate. Do NOT - touch version information after export from CVS. - All packages will use the version and release data - from configure.in. - Local files should not be changed, except prior to a CVS commit!!! - This way we are all on the same page! +>. (RPM spec files + will need to be incremented as well.)

If the default actionsfile has changed since last release, - bump up its version info in this line: +> If default.action has changed since last + release (i.e. software release or standalone actions file release), + bump up its version info to A.B in this line:

@@ -166,8 +303,7 @@ WIDTH="90%" >

  {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
-

{+add-header{X-Actions-File-Version: A.B} -filter -no-popups}

All documentation should be rebuild after the version bump. + Finished docs should be then be committed to CVS (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), and the PDF docs + fall in this category. REAMDE, the man page, AUTHORS, and config + should all also be committed to CVS for other packagers. The + formal docs should be uploaded to the webserver. See the + Section "Updating the webserver" in this manual for details. +

The User Manual is also used for context + sensitive help for the CGI editor. This is version sensitive, so that + the user will get appropriate help for his/her release. So with + each release a fresh version should be uploaded to the webserver + (this is in addition to the main User Manual + link from the main page since we need to keep manuals for various + versions available). The CGI pages will link to something like + http://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. +

All developers should look at the ChangeLog and + make sure noteworthy changes are referenced. +

Commit all files that were changed in the above steps!

The first package uploaded should be the official - "tarball" release. This is built with the - "make tarball-dist" Makefile - target, and then can be uploaded with - "make tarball-upload" (see below). +> 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.

-

8.3. SuSE or Red Hat6.3. Building and Releasing the Packages

Ensure that you have the latest code version. Hence run: -

Now the individual packages can be built and released. Note that for + GPL reasons the first package to be released is always the source tarball. +
For all types of packages, including the source tarball, + you must make sure that you build from clean sources by exporting + the right version from CVS into an empty directory (just press return when + asked for a password): +

cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current -
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
-
first. -
Do NOT change a single bit, including, but not limited to + version information after export from CVS. This is to make sure that + all release packages, and with them, all future bug reports, are based + on exactly the same code. +

autoheader && autoconf && ./configure -
Warning
-
Then do -

make suse-dist or make redhat-dist -
Every significant release of Privoxy has included at least one + package that either had incorrect versions of files, missing files, + or incidental leftovers from a previous build process that gave + unknown numbers of users headaches to try to figure out what was + wrong. PLEASE, make sure you are using pristene sources, and are + following the prescribed process! +
Please find additional instructions for the source tarball and the + individual platform dependent binary packages below. And details + on the Sourceforge release process below that. +
6.3.1. Note on Privoxy Packaging
Please keep these general guidelines in mind when putting together + your package. These apply to all platforms! +

Privoxy requires -
*.action files, all + logfiles, and the trust file. You will + need to determine the best way to do this for your platform. +
To upload the package to Sourceforge, simply issue -
Please include up to date documentation. At a bare minimum: +

LICENSE (top-level directory) +
make suse-upload or make redhat-upload -

-
Go to the displayed URL and release the file publicly on Sourceforge. -
8.4. OS/2
Ensure that you have the latest code version. Hence run: -

README (top-level directory) +
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd .. - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup -

-
You will need a mix of development tools. - 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, - autoconf and sh tools. - The packaging takes place with WarpIN, available from various sources, including - its home page: xworkplace. -
Change directory to the os2setup directory. - Edit the os2build.cmd file to set the final executable filename. - For example, -
AUTHORS (top-level directory) +
installExeName='privoxyos2_setup_X.Y.Z.exe' -

- Next, edit the IJB.wis file so the release number matches - in the PACKAGEID section: -
man page (top-level directory, Unix-like + platforms only) +
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z" -

- You're now ready to build. Run: -
The User Manual (doc/webserver/user-manual/) +
os2build -

- And in the ./files directory you will have the - WarpIN-installable executable. - Upload this anonymously to - uploads.sourceforge.net/incoming, create a release - for it, and you're done. -
8.5. Solaris
Login to Sourceforge's compilefarm via ssh -

FAQ (doc/webserver/faq/) +
ssh cf.sourceforge.net -

Also suggested: Developer Manual -
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. +
Choose the right operating system (not the Debian one). If you have - downloaded Privoxy before, +> The documentation has been designed such that the manuals are linked + to each other from parallel directories, and should be packaged + that way. privoxy-index.html can also be + included and can serve as a focal point for docs and other links of + interest (and possibly renamed to index.html). + This should be one level up from the manuals. There is a link also + on this page to an HTMLized version of the man page. To avoid 404 for + this, it is in CVS as + doc/webserver/man-page/privoxy-man-page.html, + and should be included along with the manuals. There is also a + css stylesheets that can be included for better presentation: + p_doc.css. This should be in the same directory + with privoxy-index.html, (i.e. one level up from + the manual directories). +
user.action and user.filter + are designed for local preferences. Make sure these do not get overwritten! + config should not be overwritten either. This + has especially important configuration data in it. + trust should be left in tact as well. +
Other configuration files (default.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 + likely to change between releases and contain important new features + and bug fixes. +
Please check platform specific notes in this doc, if you haven't + done "Privoxy" packaging before for other platform + specific issues. Conversely, please add any notes that you know + are important for your platform (or contact one of the doc + maintainers to do this if you can't). +
Packagers should do a "clean" install of their + package after building it. So any previous installs should be + removed first to ensure the integrity of the newly built package. + Then run the package for a while to make sure there are no + obvious problems, before uploading. +
+
6.3.2. Source Tarball
First, make sure that you have freshly exported the right + version into an empty directory. (See "Building and releasing + packages" above). Then run:

cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current -
cd current + autoheader && autoconf && ./configure

If not, please checkout - Privoxy via CVS first. Run: +> Then do:

autoheader && autoconf && ./configure -
make tarball-dist

Then run +> To upload the package to Sourceforge, simply issue

gmake solaris-dist -
make tarball-upload

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. -
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. +
8.6. Windows
6.3.3. 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 CVS, + 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. +
Ensure that you have the latest code version. Hence run +> Then run:

cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current -
cd current + autoheader && autoconf && ./configure

Run: +> Then do

autoheader && autoconf && ./configure -
make dist-dist

Then do FIXME. -
8.7. Debian
Ensure that you have the latest code version. Hence run: +> To upload the package to Sourceforge, simply issue

cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current -
make dist-upload rpm_packagerev

first. Run: +> 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. +
6.3.4. OS/2
First, make sure that you have freshly exported the right + version into an empty directory. (See "Building and releasing + packages" above). Then get the OS/2 Setup module:

autoheader && autoconf && ./configure -
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup

Then do FIXME. +> You will need a mix of development tools. + 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, + autoconf and sh tools. + The packaging takes place with WarpIN, available from various sources, including + its home page: xworkplace.
8.8. Mac OSX
Ensure that you have the latest code version. Hence run: +> Change directory to the os2setup directory. + Edit the os2build.cmd file to set the final executable filename. + For example,

cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd .. - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup -
installExeName='privoxyos2_setup_X.Y.Z.exe'

From the osxsetup directory, run: - Next, edit the IJB.wis file so the release number matches + in the PACKAGEID section: +

build -
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"

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. +> You're now ready to build. Run:
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 -
os2build
- You can then upload
You will find the WarpIN-installable executable in the + privoxyosx_setup_x.y.z.zip anonymously to - ./files directory. Upload this anonymously to + uploads.sourceforge.net/incoming, - create a release for it, and you're done. +>, create a release + for it, and you're done. Use the release notes and Change Log from the + source tarball package.
8.9. FreeBSD
6.3.5. Solaris Change the version number of Privoxy in the - configure.in file. Run: - Login to Sourceforge's compilefarm via ssh: + autoheader && autoconf && ./configure - ssh cf.sourceforge.net - Then ... - Login to Sourceforge's compilefarm via ssh: +> 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: ssh cf.sourceforge.net - cd current + autoheader && autoconf && ./configure Choose the right operating system. +> Then run cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current - gmake solaris-dist Run: +> 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.
6.3.6. Windows
You should ensure you have the latest version of Cygwin (from + http://www.cygwin.com/). + Run the following commands from within a Cygwin bash shell. + 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: + autoheader && autoconf && ./configure - cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup -
Then run: -
Then you can build the package. This is fully automated, and is + controlled by winsetup/GNUmakefile. + All you need to do is: + gmake freebsd-dist - cd winsetup + make - which creates a gzip'ed tar archive. Sadly, you cannot use make - freebsd-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. - 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 + and Change Log from the source tarball package. +
8.10. Tarball
6.3.7. Debian Ensure that you have the right code version. Hence run: - 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: + cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current - debchange -v 3.0.12-stable-1 "New upstream version" - Then, run: + dpkg-buildpackage -rfakeroot -us -uc -b + This will create + ../privoxy_3.0.12-stable-1_i386.deb + which can be uploaded. To upload the package to Sourceforge, simply + issue + make debian-upload +
6.3.8. Mac OS X
first. Run: +> First, make sure that you have freshly exported the right + version into an empty directory. (See "Building and releasing + packages" above). Then get the Mac OS X setup module:
autoheader && autoconf && ./configure - cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
Then do: +> Then run:
make tarball-dist - cd osxsetup + build
To upload the package to Sourceforge, simply issue +> 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:
make tarball-upload - zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
Goto the displayed URL and release the file publicly on Sourceforge. -
You can then upload privoxyosx_setup_x.y.z.zip anonymously to + uploads.sourceforge.net/incoming, + create a release for it, and you're done. Use the release notes + and Change Log from the source tarball package. +
8.11. HP-UX 11
6.3.9. FreeBSD Ensure that you have the latest code version. Hence run: +> Login to Sourceforge's compile-farm via ssh: cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current - ssh cf.sourceforge.net first. Run: +> Choose the right operating system. + 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: autoheader && autoconf && ./configure - cd current + autoheader && autoconf && ./configure Then do FIXME. -
8.12. Amiga OS
Ensure that you have the latest code version. Hence run: +> Then run:
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current - gmake freebsd-dist
first. Run: +> which creates a gzip'ed tar archive. Sadly, you cannot use make + freebsd-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. +
6.3.10. HP-UX 11
First, make sure that you have freshly exported the right + version into an empty directory. (See "Building and releasing + packages" above). Then run:
autoheader && autoconf && ./configure - cd current + autoheader && autoconf && ./configure
8.13. AIX
6.3.11. Amiga OS Login to Sourceforge's compilefarm via ssh: +> First, make sure that you have freshly exported the right + version into an empty directory. (See "Building and releasing + packages" above). Then run: ssh cf.sourceforge.net - cd current + autoheader && autoconf && ./configure Choose the right operating system. If you have downloaded Privoxy - before: +> Then do FIXME. +
6.3.12. AIX
Login to Sourceforge's compilefarm via ssh:
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current - cd current - ssh cf.sourceforge.net
If not, please checkout - Privoxy via CVS first. Run: +> Choose the right operating system. + 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:
autoheader && autoconf && ./configure - cd current + autoheader && autoconf && ./configure
make aix-dist -
make aix-dist on the Sourceforge machine (no ncftpput). You now have to manually upload the archive to Sourceforge's ftp server and release - the file publicly. + the file publicly. Use the release notes and Change Log from the + source tarball package.

6.1. Version numbers

8.1. Before the Release6.2. Before the Release: Freeze

`8.2. Update the webserver`

8.3. SuSE or Red Hat6.3. Building and Releasing the Packages

6.3.1. Note on Privoxy Packaging

8.4. OS/2

8.5. Solaris

6.3.2. Source Tarball

8.6. Windows

8.7. Debian

6.3.4. OS/2

8.8. Mac OSX

`8.9. FreeBSD`

`6.3.6. Windows`

`8.10. Tarball`

`6.3.8. Mac OS X`

`8.11. HP-UX 11`

`8.12. Amiga OS`

`6.3.10. HP-UX 11`

`8.13. AIX`

`6.3.12. AIX`

`6.4. Uploading and Releasing Your Package`

`6.5. After the Release`