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: ncftpput (ncftp), scp, ssh - (ssh), gmake (GNU's version of make), autoconf, - cvs.
- -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:
- -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).
-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. - (RPM spec files will need to be incremented as well.)
-Update the code status (CODE_STATUS="xxx") in configure.in to one of "alpha", "beta" or - "stable".
-If action file processing has changed and is not - backward-compatable, make sure the "for-privoxy-version=x.y.z" - minimum version number in default.action.master has been - updated:
- -
-
-{{settings}}
+
+ |
Do NOT change a single bit, including, but not limited to + version information after export from Git. This is to make sure that + all release packages, and with them, all future bug reports, are based + on exactly the same code. +
| Warning |
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. +
Please keep these general guidelines in mind when putting together + your package. These apply to all platforms! +
Privoxy requires + write access to: all *.action files, all + logfiles, and the trust file. You will + need to determine the best way to do this for your platform. +
Please include up to date documentation. At a bare minimum: +
| LICENSE (top-level directory) + |
| README (top-level directory) + |
| AUTHORS (top-level directory) + |
| man page (top-level directory, Unix-like + platforms only) + |
| The User Manual (doc/webserver/user-manual/) + |
| FAQ (doc/webserver/faq/) + |
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. +
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 Git 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. +
First, 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 do: +
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. +
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. +
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: +
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.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, +
installExeName='privoxyos2_setup_X.Y.Z.exe' |
Next, edit the IJB.wis file so the release number matches + in the PACKAGEID section: +
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z" |
You're now ready to build. Run: +
os2build |
You will find the WarpIN-installable executable in the + ./files directory. Upload this 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. +
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. +
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 you can build the package. This is fully automated, and is + controlled by windows/GNUmakefile. + All you need to do is: +
cd windows + make |
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, +
$ 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. +
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: +
debchange -v 3.0.27-UNRELEASED-1 "New upstream version" |
Then, run: +
dpkg-buildpackage -rfakeroot -us -uc -b |
This will create + ../privoxy_3.0.27-UNRELEASED-1_i386.deb + which can be uploaded. To upload the package to Sourceforge, simply + issue +
make debian-upload |
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 Git repository 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 generates 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: +
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. +
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 Git 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 package is for whichversion of OS X.
-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.
-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 -- |
-
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.
-Update the www/privoxy port and submit a diff upstream. For - details see the FreeBSD Porter's Handbook.
-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. 3.0.26 (beta).
- -Now just follow the prompts. Be sure to add any appropriate Release - notes. You should see your freshly uploaded packages in "Step 2. Add Files To This Release". Check the - appropriate box(es). Remember at each step to hit the "Refresh/Submit" buttons! You should now see your - file(s) listed in Step 3. Fill out the forms with the appropriate - information for your platform, being sure to hit "Update" for each file. If anyone is monitoring your - platform, check the "email" box at the very - bottom to notify them of the new package. This should do it!
- -If you have made errors, or need to make changes, you can go through - essentially the same steps, but select Edit - Release, instead of Add 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 include the 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.
-The macsetup module is ideal if you wish to build and install Privoxy + from source on a single machine. +
Check out the module from Git as follows into a folder parallel to the + exported privoxy source: +
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup |
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. +
Update the www/privoxy port and submit a diff upstream. + For details see the FreeBSD Porter's Handbook. +
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. 3.0.27 + (beta). +
Now just follow the prompts. Be sure to add any appropriate Release + notes. You should see your freshly uploaded packages in + "Step 2. Add Files To This Release". Check the + appropriate box(es). Remember at each step to hit the + "Refresh/Submit" buttons! You should now see your + file(s) listed in Step 3. Fill out the forms with the appropriate + information for your platform, being sure to hit "Update" + for each file. If anyone is monitoring your platform, check the + "email" box at the very bottom to notify them of + the new package. This should do it! +
If you have made errors, or need to make changes, you can go through + essentially the same steps, but select Edit Release, + instead of Add 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 + include the + 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. +