1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 >Releasing a New Version</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
13 TITLE="Testing Guidelines"
14 HREF="testing.html"><LINK
16 TITLE="Update the Webserver"
17 HREF="webserver-update.html"><LINK
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
23 charset=ISO-8859-1"></HEAD
34 SUMMARY="Header navigation table"
43 >Privoxy Developer Manual</TH
65 HREF="webserver-update.html"
80 >6. Releasing a New Version</A
83 > When we release versions of <SPAN
87 our work leaves our cozy secret lab and has to work in the cold
88 RealWorld[tm]. Once it is released, there is no way to call it
89 back, so it is very important that great care is taken to ensure
90 that everything runs fine, and not to introduce problems in the
94 > So when releasing a new version, please adhere exactly to the
95 procedure outlined in this chapter.
98 > The following programs are required to follow this process:
109 > (GNU's version of make), autoconf, cvs.
116 NAME="VERSIONNUMBERS"
117 >6.1. Version numbers</A
120 > First you need to determine which version number the release will have.
124 > version numbers consist of three numbers,
125 separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
132 > X, the version major, is rarely ever changed. It is increased by one if
133 turning a development branch into stable substantially changes the functionality,
134 user interface or configuration syntax. Majors 1 and 2 were
138 >, and 3 will be the first stable
148 Y, the version minor, represents the branch within the major version.
149 At any point in time, there are two branches being maintained:
150 The stable branch, with an even minor, say, 2N, in which no functionality is
151 being added and only bug-fixes are made, and 2N+1, the development branch, in
152 which the further development of <SPAN
157 This enables us to turn the code upside down and inside out, while at the same time
158 providing and maintaining a stable version.
159 The minor is reset to zero (and one) when the major is incremented. When a development
160 branch has matured to the point where it can be turned into stable, the old stable branch
161 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
162 new stable branch 2N+2, and a new development branch 2N+3 is opened.
167 > Z, the point or sub version, represents a release of the software within a branch.
168 It is therefore incremented immediately after each software release.
170 The point version is reset to zero when the minor changes.
173 > Stable branches work a little differently, since there should be
174 little to no development happening in such branches. Remember,
175 only bugfixes, which presumably should have had some testing
176 before being committed. Stable branches will then have their
177 version reported as <TT
180 >, during that period
181 between releases when changes are being added. This is to denote
182 that this code is <SPAN
189 as the release nears, the version is bumped according: e.g.
192 >3.0.1 -> 0.0.0 -> 3.0.2</TT
198 > In summary, the main Git trunk is the development branch where new
199 features are being worked on for the next stable series. This should
200 almost always be where the most activity takes place. There is always at
201 least one stable branch from the trunk, e.g now it is
205 >, which is only used to release stable versions.
206 Once the initial *.0 release of the stable branch has been done, then as a
207 rule, only bugfixes that have had prior testing should be committed to
208 the stable branch. Once there are enough bugfixes to justify a new
209 release, the version of this branch is again incremented Example: 3.0.0
210 -> 3.0.1 -> 3.0.2, etc are all stable releases from within the stable
211 branch. 3.1.x is currently the main trunk, and where work on 3.2.x is
212 taking place. If any questions, please post to the devel list
219 > committing to a stable branch!
222 > Developers should remember too that if they commit a bugfix to the stable
223 branch, this will more than likely require a separate submission to the
224 main trunk, since these are separate development trees within Git. If you
225 are working on both, then this would require at least two separate check
226 outs (i.e main trunk, <SPAN
232 > the stable release branch,
245 >6.2. Before the Release: Freeze</A
248 > The following <SPAN
252 >must be done by one of the
255 > prior to each new release.
262 > Make sure that everybody who has worked on the code in the last
263 couple of days has had a chance to yell <SPAN
267 they have pending changes/fixes in their pipelines. Announce the
268 freeze so that nobody will interfere with last minute changes.
273 > Update the code status (CODE_STATUS="xxx") in configure.in to one of
274 "alpha", "beta" or "stable".
279 > Rebuild configure and GNUMakefile to make sure the updated values are being used.
288 CLASS="PROGRAMLISTING"
289 >$ autoheader && autoconf # rebuild configure
290 $ ./configure # rebuild GNUmakefile</PRE
300 > to update the sgml documentation source files.
305 > If action file processing has changed and is not backward-compatible,
306 make sure the "for-privoxy-version=x.y.z" minimum version number in
307 default.action.master has been updated:
316 CLASS="PROGRAMLISTING"
318 #############################################################################
319 #MASTER# COMMENT: The minimum Privoxy version:
320 for-privoxy-version=3.0.11</PRE
327 > All documentation should be rebuild after the code status has been changed.
328 Finished docs should be then be committed to Git (for those
329 without the ability to build these). Some docs may require
330 rather obscure processing tools. <TT
334 the man page (and the html version of the man page)
335 fall in this category. README, the man page, AUTHORS, and config
336 should all also be committed to Git for other packagers. The
337 formal docs should be uploaded to the webserver. See the section
339 HREF="webserver-update.html"
341 >"Updating the webserver"</A
343 in this manual for details.
351 > is also used for context
352 sensitive help for the CGI editor. This is version sensitive, so that
353 the user will get appropriate help for his/her release. So with
354 each release a fresh version should be uploaded to the webserver
355 (this is in addition to the main <I
359 link from the main page since we need to keep manuals for various
360 versions available). The CGI pages will link to something like
363 >http://privoxy.org/$(VERSION)/user-manual/</TT
365 will need to be updated for each new release. There is no Makefile
366 target for this at this time!!! It needs to be done manually.
371 > All developers should look at the <TT
375 make sure noteworthy changes are referenced.
384 >Commit all files that were changed in the above steps!</I
391 > Tag all files in Git with the version number with
399 Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
404 > If the release was in a development branch, increase the point version
405 from even to odd (X.Y.(Z+1)) again in <TT
414 > On the webserver, copy the user manual to a new top-level directory
418 >. This ensures that help links from the CGI
419 pages, which have the version as a prefix, will go into the right version of the manual.
420 If this is a development branch release, also symlink <TT
445 >6.3. Building and Releasing the Packages</A
448 > Now the individual packages can be built and released. Note that for
449 GPL reasons the first package to be released is always the source tarball.
458 > types of packages, including the source tarball,
463 >you must make sure that you build from clean sources by exporting
464 the right version from Git into an empty directory</I
466 > (just press return when
467 asked for a password):
476 CLASS="PROGRAMLISTING"
477 > mkdir dist # delete or choose different name if it already exists
479 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
480 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current</PRE
491 > a single bit, including, but not limited to
492 version information after export from Git. This is to make sure that
493 all release packages, and with them, all future bug reports, are based
494 on exactly the same code.
515 > Every significant release of Privoxy has included at least one
516 package that either had incorrect versions of files, missing files,
517 or incidental leftovers from a previous build process that gave
518 unknown numbers of users headaches to try to figure out what was
519 wrong. PLEASE, make sure you are using pristene sources, and are
520 following the prescribed process!
527 > Please find additional instructions for the source tarball and the
528 individual platform dependent binary packages below. And details
529 on the Sourceforge release process below that.
536 NAME="PACK-GUIDELINES"
537 >6.3.1. Note on Privoxy Packaging</A
540 > Please keep these general guidelines in mind when putting together
541 your package. These apply to <SPAN
564 write access to: all <TT
568 logfiles, and the <TT
572 need to determine the best way to do this for your platform.
577 > Please include up to date documentation. At a bare minimum:
589 > (top-level directory)
606 > (top-level directory)
623 > (top-level directory)
640 > (top-level directory, Unix-like
658 > (doc/webserver/user-manual/)
675 > (doc/webserver/faq/)
683 > Also suggested: <TT
685 >Developer Manual</TT
687 (doc/webserver/developer-manual) and <TT
691 (top-level directory). <TT
694 > and the manuals are
695 HTML docs. There are also text versions in
699 > which could conceivably also be
703 > The documentation has been designed such that the manuals are linked
704 to each other from parallel directories, and should be packaged
707 >privoxy-index.html</TT
709 included and can serve as a focal point for docs and other links of
710 interest (and possibly renamed to <TT
714 This should be one level up from the manuals. There is a link also
715 on this page to an HTMLized version of the man page. To avoid 404 for
716 this, it is in Git as
719 >doc/webserver/man-page/privoxy-man-page.html</TT
721 and should be included along with the manuals. There is also a
722 css stylesheets that can be included for better presentation:
726 >. This should be in the same directory
729 >privoxy-index.html</TT
730 >, (i.e. one level up from
731 the manual directories).
743 are designed for local preferences. Make sure these do not get overwritten!
747 > should not be overwritten either. This
748 has especially important configuration data in it.
752 > should be left in tact as well.
757 > Other configuration files (<TT
764 >) should be installed as the new
765 defaults, but all previously installed configuration files should be
766 preserved as backups. This is just good manners :-) These files are
767 likely to change between releases and contain important new features
773 > Please check platform specific notes in this doc, if you haven't
777 > packaging before for other platform
778 specific issues. Conversely, please add any notes that you know
779 are important for your platform (or contact one of the doc
780 maintainers to do this if you can't).
785 > Packagers should do a <SPAN
789 package after building it. So any previous installs should be
790 removed first to ensure the integrity of the newly built package.
791 Then run the package for a while to make sure there are no
792 obvious problems, before uploading.
802 NAME="NEWRELEASE-TARBALL"
803 >6.3.2. Source Tarball</A
810 >make sure that you have freshly exported the right
811 version into an empty directory</I
813 >. (See "Building and releasing
814 packages" above). Then run:
823 CLASS="PROGRAMLISTING"
825 autoheader && autoconf && ./configure</PRE
839 CLASS="PROGRAMLISTING"
840 > make tarball-dist</PRE
845 > To upload the package to Sourceforge, simply issue
854 CLASS="PROGRAMLISTING"
855 > make tarball-upload</PRE
860 > Go to the displayed URL and release the file publicly on Sourceforge.
861 For the change log field, use the relevant section of the
873 NAME="NEWRELEASE-RPM"
874 >6.3.3. SuSE, Conectiva or Red Hat RPM</A
877 > In following text, replace <TT
886 > for Red Hat or <SPAN
896 >make sure that you have freshly exported the right
897 version into an empty directory</I
899 >. (See "Building and releasing
903 > As the only exception to not changing anything after export from Git,
904 now examine the file <TT
916 and make sure that the version information and the RPM release number are
917 correct. The RPM release numbers for each version start at one. Hence it must
918 be reset to one if this is the first RPM for
924 > which is built from version
927 HREF="https://sourceforge.net/project/showfiles.php?group_id=11118"
931 > if unsure. Else, it must be set to the highest already available RPM
932 release number for that version plus one.
944 CLASS="PROGRAMLISTING"
946 autoheader && autoconf && ./configure</PRE
960 CLASS="PROGRAMLISTING"
971 > To upload the package to Sourceforge, simply issue
980 CLASS="PROGRAMLISTING"
1002 RPM release number as determined above.
1003 Go to the displayed URL and release the file publicly on Sourceforge.
1004 Use the release notes and change log from the source tarball package.
1012 NAME="NEWRELEASE-OS2"
1020 >make sure that you have freshly exported the right
1021 version into an empty directory</I
1023 >. (See "Building and releasing
1024 packages" above). Then get the OS/2 Setup module:
1033 CLASS="PROGRAMLISTING"
1034 > cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup</PRE
1039 > You will need a mix of development tools.
1040 The main compilation takes place with IBM Visual Age C++.
1041 Some ancillary work takes place with GNU tools, available from
1042 various sources like hobbes.nmsu.edu.
1043 Specificially, you will need <TT
1054 The packaging takes place with WarpIN, available from various sources, including
1056 HREF="http://www.xworkplace.org/"
1062 > Change directory to the <TT
1066 Edit the os2build.cmd file to set the final executable filename.
1076 CLASS="PROGRAMLISTING"
1077 > installExeName='privoxyos2_setup_X.Y.Z.exe'</PRE
1082 > Next, edit the <TT
1085 > file so the release number matches
1098 CLASS="PROGRAMLISTING"
1099 > PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"</PRE
1104 > You're now ready to build. Run:
1113 CLASS="PROGRAMLISTING"
1119 > You will find the WarpIN-installable executable in the
1123 > directory. Upload this anonymously to
1126 >uploads.sourceforge.net/incoming</TT
1128 for it, and you're done. Use the release notes and Change Log from the
1129 source tarball package.
1137 NAME="NEWRELEASE-SOLARIS"
1141 > Login to Sourceforge's compilefarm via ssh:
1150 CLASS="PROGRAMLISTING"
1151 > ssh cf.sourceforge.net</PRE
1156 > Choose the right operating system (not the Debian one).
1157 When logged in, <SPAN
1161 >make sure that you have freshly exported the right
1162 version into an empty directory</I
1164 >. (See "Building and releasing
1165 packages" above). Then run:
1174 CLASS="PROGRAMLISTING"
1176 autoheader && autoconf && ./configure</PRE
1190 CLASS="PROGRAMLISTING"
1191 > gmake solaris-dist</PRE
1196 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1200 > on the Sourceforge machine (no ncftpput). You now have
1201 to manually upload the archive to Sourceforge's ftp server and release
1202 the file publicly. Use the release notes and Change Log from the
1203 source tarball package.
1211 NAME="NEWRELEASE-WINDOWS"
1215 > Note that the docbook generated files might need some hand editing,
1216 so the Windows build makefile does not rebuild the docs.
1223 >make sure that you have freshly exported the right
1224 version into an empty directory</I
1226 >. (See "Building and releasing
1231 > Then you can build the package. This is fully automated, and is
1234 >windows/GNUmakefile</TT
1236 All you need to do is:
1245 CLASS="PROGRAMLISTING"
1252 > Now you can manually rename <TT
1254 >privoxy_setup.exe</TT
1258 >privoxy_setup_X.Y.Z.exe</TT
1267 Create a .zip file of the newly renamed <TT
1271 GPG sign the installer and zip file,
1280 CLASS="PROGRAMLISTING"
1281 > $ gpg --armor --detach --sign <TT
1283 >privoxy_setup_X.Y.Z.exe</TT
1285 $ gpg --armor --detach --sign <TT
1287 >privoxy_X.Y.Z.zip</TT
1293 > and upload the files to SourceForge.
1296 > When releasing the package on SourceForge, use the release notes
1297 and Change Log from the source tarball package.
1305 NAME="NEWRELEASE-DEBIAN"
1313 >make sure that you have freshly exported the
1314 right version into an empty directory</I
1317 "Building and releasing packages" above). Then add a log
1320 >debian/changelog</TT
1322 already there, for example by running:
1331 CLASS="PROGRAMLISTING"
1332 > debchange -v 3.0.27-UNRELEASED-1 "New upstream version"</PRE
1346 CLASS="PROGRAMLISTING"
1347 > dpkg-buildpackage -rfakeroot -us -uc -b</PRE
1355 >../privoxy_3.0.27-UNRELEASED-1_i386.deb</TT
1357 which can be uploaded. To upload the package to Sourceforge, simply
1367 CLASS="PROGRAMLISTING"
1368 > make debian-upload</PRE
1378 NAME="NEWRELEASE-MACOSX"
1386 >make sure that you have freshly exported the right
1387 version into an empty directory</I
1389 >. (See "Building and releasing
1393 > There are three modules available in the Git repository for use on Mac
1394 OS X, though technically only two of them generate a release (the other
1395 can be used to install from source).
1402 NAME="OS-X-OSXPACKAGEBUILDER-MODULE"
1403 >6.3.8.1. OSXPackageBuilder module</A
1406 > The OSXPackageBuilder module generates OS X installer packages
1407 supporting all Macs running OS X 10.4 and above. Obtain it from Git as
1408 follows into a folder parallel to the exported privoxy source:
1417 CLASS="PROGRAMLISTING"
1418 > cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder</PRE
1423 > The module contains complete instructions on its usage in the file
1426 >OS X Package Builder HOWTO.txt</TT
1430 > Once the package(s) have been generated, you can then upload them
1431 directly to the Files section of the Sourceforge project in the
1432 Macintosh (OS X) folder. Each new version release of Privoxy should
1433 have a new subfolder created in which to store its files. Please
1434 ensure that the folder contains a readme file that makes it clear
1435 which package is for whichversion of OS X.
1443 NAME="OS-X-OSXSETUP-MODULE"
1444 >6.3.8.2. osxsetup module (DEPRECATED)</A
1451 >This module is deprecated since the installer it generates
1452 places all Privoxy files in one folder in a non-standard location, and
1453 supports only Intel Macs running OS X 10.6 or higher.</I
1458 > Check out the module from Git as follows into a folder parallel to the
1459 exported privoxy source:
1468 CLASS="PROGRAMLISTING"
1469 > cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup</PRE
1483 CLASS="PROGRAMLISTING"
1504 Finally, it will copy over the necessary files to the ./osxsetup/files
1505 directory for further processing by <TT
1511 > Bring up PackageMaker with the PrivoxyPackage.pmsp definition file,
1512 modify the package name to match the release, and hit the "Create
1513 package" button. If you specify ./Privoxy.pkg as the output package
1514 name, you can then create the distributable zip file with the command:
1523 CLASS="PROGRAMLISTING"
1524 > zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg</PRE
1529 > You can then upload this file directly to the Files section of the
1530 Sourceforge project in the Macintosh (OS X) folder. Each new version
1531 release of Privoxy should have a new subfolder created in which to
1533 Please ensure that the folder contains a readme file that makes it
1534 clear which version(s) of OS X the package supports.
1542 NAME="OS-X-MACSETUP-MODULE"
1543 >6.3.8.3. macsetup module</A
1546 > The macsetup module is ideal if you wish to build and install Privoxy
1547 from source on a single machine.
1550 > Check out the module from Git as follows into a folder parallel to the
1551 exported privoxy source:
1560 CLASS="PROGRAMLISTING"
1561 > cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup</PRE
1566 > The module contains complete instructions on its usage in its
1570 > file. The end result will be the
1571 exported version of Privoxy installed on the build machine.
1580 NAME="NEWRELEASE-FREEBSD"
1584 > Update the www/privoxy port and submit a diff upstream.
1585 For details see the <A
1586 HREF="https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/"
1588 >FreeBSD Porter's Handbook</A
1599 >6.4. Uploading and Releasing Your Package</A
1602 > After the package is ready, it is time to upload it
1603 to SourceForge, and go through the release steps. The upload
1612 HREF="ftp://upload.sourceforge.net/incoming"
1614 >ftp://upload.sourceforge.net/incoming</A
1630 >ijbswa-developers@lists.sourceforge.net</TT
1639 > targets as described above.
1642 > Once this done go to
1644 HREF="https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
1646 > https://sourceforge.net/project/admin/editpackages.php?group_id=11118</A
1648 making sure you are logged in. Find your target platform in the
1649 second column, and click <TT
1653 then need to create a new release for your package, using the format
1656 >$VERSION ($CODE_STATUS)</TT
1667 > Now just follow the prompts. Be sure to add any appropriate Release
1668 notes. You should see your freshly uploaded packages in
1671 >"Step 2. Add Files To This Release"</SPAN
1673 appropriate box(es). Remember at each step to hit the
1676 >"Refresh/Submit"</SPAN
1677 > buttons! You should now see your
1678 file(s) listed in Step 3. Fill out the forms with the appropriate
1679 information for your platform, being sure to hit <SPAN
1683 for each file. If anyone is monitoring your platform, check the
1687 > box at the very bottom to notify them of
1688 the new package. This should do it!
1691 > If you have made errors, or need to make changes, you can go through
1692 essentially the same steps, but select <TT
1708 >6.5. After the Release</A
1711 > When all (or: most of the) packages have been uploaded and made available,
1712 send an email to the
1714 HREF="mailto:privoxy-announce@lists.privoxy.org"
1718 >, Subject: "Version X.Y.Z available for download". Be sure to
1721 HREF="https://sourceforge.net/project/showfiles.php?group_id=11118"
1723 > download location</A
1724 >, the release notes and the Changelog. Also, post an
1725 updated News item on the project page Sourceforge, and update the Home
1726 page and docs linked from the Home page (see below). Other news sites
1727 and release oriented sites, such as Freshmeat, should also be notified.
1730 > Then update the source code for the next version to be released:
1737 > Increment the version number and change the code status to "UNRELEASED"
1746 > Rebuild configure (<SPAN
1750 >autoheader && autoconf</B
1753 and GNUMakefile (<SPAN
1768 >make dok-release</B
1770 > to update the sgml documentation source files.
1775 > Commit all your changes.
1786 SUMMARY="Footer navigation table"
1815 HREF="webserver-update.html"
1825 >Testing Guidelines</TD
1835 >Update the Webserver</TD