4 >Releasing a New Version</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
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"></HEAD
31 SUMMARY="Header navigation table"
40 >Privoxy Developer Manual</TH
62 HREF="webserver-update.html"
76 NAME="NEWRELEASE">6. Releasing a New Version</H1
78 > When we release versions of <SPAN
82 our work leaves our cozy secret lab and has to work in the cold
83 RealWorld[tm]. Once it is released, there is no way to call it
84 back, so it is very important that great care is taken to ensure
85 that everything runs fine, and not to introduce problems in the
89 > So when releasing a new version, please adhere exactly to the
90 procedure outlined in this chapter.
93 > The following programs are required to follow this process:
104 > (GNU's version of make), autoconf, cvs.
111 NAME="VERSIONNUMBERS">6.1. Version numbers</H2
113 > First you need to determine which version number the release will have.
117 > version numbers consist of three numbers,
118 separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
124 > X, the version major, is rarely ever changed. It is increased by one if
125 turning a development branch into stable substantially changes the functionality,
126 user interface or configuration syntax. Majors 1 and 2 were
130 >, and 3 will be the first stable
139 > Y, the version minor, represents the branch within the major version.
140 At any point in time, there are two branches being maintained:
141 The stable branch, with an even minor, say, 2N, in which no functionality is
142 being added and only bug-fixes are made, and 2N+1, the development branch, in
143 which the further development of <SPAN
148 This enables us to turn the code upside down and inside out, while at the same time
149 providing and maintaining a stable version.
150 The minor is reset to zero (and one) when the major is incremented. When a development
151 branch has matured to the point where it can be turned into stable, the old stable branch
152 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
153 new stable branch 2N+2, and a new development branch 2N+3 is opened.
158 > Z, the point or sub version, represents a release of the software within a branch.
159 It is therefore incremented immediately before each code freeze.
160 In development branches, only the even point versions correspond to actual releases,
161 while the odd ones denote the evolving state of the sources on CVS in between.
162 It follows that Z is odd on CVS in development branches most of the time. There, it gets
163 increased to an even number immediately before a code freeze, and is increased to an odd
164 number again immediately thereafter.
165 This ensures that builds from CVS snapshots are easily distinguished from released versions.
166 The point version is reset to zero when the minor changes.
173 > In summary, the main CVS trunk is the development branch where new
174 features are being worked on for the next stable series. This should
175 almost always be where the most activity takes place. There is always at
176 least one stable branch from the trunk, e.g now it is 3.0, which is only
177 used to release stable versions. Once the initial .0 release of the
178 stable branch has been done, then as a rule, only bugfixes that have had
179 prior testing should be committed to the stable branch. At that point, it
183 >. Once there are enough bugfixes to
184 justify a new release, the version of this branch is again incremented
185 Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable releases from within
186 the stable branch. 3.1.x is currently the main trunk, and where work on
187 3.2.x is taking place. If any questions, please post to the devel list
194 > committing to a stable branch!
203 NAME="BEFORERELEASE">6.2. Before the Release: Freeze</H2
205 > The following <SPAN
209 >must be done by one of the
212 > prior to each new release.
220 > Make sure that everybody who has worked on the code in the last
221 couple of days has had a chance to yell <SPAN
225 they have pending changes/fixes in their pipelines. Announce the
226 freeze so that nobody will interfere with last minute changes.
231 > Increment the version number (point from odd to even in development
236 will need to be incremented as well.)
244 > has changed since last
245 release (i.e. software release or standalone actions file release),
246 bump up its version info to A.B in this line:
257 CLASS="PROGRAMLISTING"
258 > {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}</PRE
266 Then change the version info in doc/webserver/actions/index.php,
267 line: '$required_actions_file_version = "A.B";'
272 > All documentation should be rebuild after the version bump.
273 Finished docs should be then be committed to CVS (for those
274 without the ability to build these). Some docs may require
275 rather obscure processing tools. <TT
279 the man page (and the html version of the man page), and the PDF docs
280 fall in this category. REAMDE, the man page, AUTHORS, and config
281 should all also be committed to CVS for other packagers. The
282 formal docs should be uploaded to the webserver. See the
283 Section "Updating the webserver" in this manual for details.
291 > is also used for context
292 sensitive help for the CGI editor. This is version sensitive, so that
293 the user will get appropriate help for his/her release. So with
294 each release a fresh version should be uploaded to the webserver
295 (this is in addition to the main <I
299 link from the main page since we need to keep manuals for various
300 versions available). The CGI pages will link to something like
303 >http://privoxy.org/$(VERSION)/user-manual/</TT
305 will need to be updated for each new release. There is no Makefile
306 target for this at this time!!! It needs to be done manually.
311 > All developers should look at the <TT
315 make sure noteworthy changes are referenced.
324 >Commit all files that were changed in the above steps!</I
331 > Tag all files in CVS with the version number with
339 Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
344 > If the release was in a development branch, increase the point version
345 from even to odd (X.Y.(Z+1)) again in <TT
354 > On the webserver, copy the user manual to a new top-level directory
358 >. This ensures that help links from the CGI
359 pages, which have the version as a prefix, will go into the right version of the manual.
360 If this is a development branch release, also symlink <TT
386 NAME="THERELEASE">6.3. Building and Releasing the Packages</H2
388 > Now the individual packages can be built and released. Note that for
389 GPL reasons the first package to be released is always the source tarball.
398 > types of packages, including the source tarball,
403 >you must make sure that you build from clean sources by exporting
404 the right version from CVS into an empty directory</I
406 > (just press return when
407 asked for a password):
417 CLASS="PROGRAMLISTING"
418 > mkdir dist # delete or choose different name if it already exists
420 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
421 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current</PRE
434 > a single bit, including, but not limited to
435 version information after export from CVS. This is to make sure that
436 all release packages, and with them, all future bug reports, are based
437 on exactly the same code.
440 > Please find additional instructions for the source tarball and the
441 individual platform dependent binary packages below. And details
442 on the Sourceforge release process below that.
449 NAME="PACK-GUIDELINES">6.3.1. Note on Privoxy Packaging</H3
451 > Please keep these general guidelines in mind when putting together
452 your package. These apply to <SPAN
476 write access to: all <TT
480 logfiles, and the <TT
484 need to determine the best way to do this for your platform.
489 > Please include up to date documentation. At a bare minimum:
501 > (top-level directory)
518 > (top-level directory)
535 > (top-level directory)
552 > (top-level directory, Unix-like
570 > (doc/webserver/user-manual/)
587 > (doc/webserver/faq/)
595 > Also suggested: <TT
597 >Developer Manual</TT
599 (doc/webserver/developer-manual) and <TT
603 (top-level directory). <TT
606 > and the manuals are
607 HTML docs. There are also text versions in
611 > which could conceivably also be
615 > The documentation has been designed such that the manuals are linked
616 to each other from parallel directories, and should be packaged
619 >privoxy-index.html</TT
621 included and can serve as a focal point for docs and other links of
622 interest (and possibly renamed to <TT
626 This should be one level up from the manuals. There is a link also
627 on this page to an HTMLized version of the man page. To avoid 404 for
628 this, it is in CVS as
631 >doc/webserver/man-page/privoxy-man-page.html</TT
633 and should be included along with the manuals. There is also a
634 css stylesheets that can be included for better presentation:
638 >. This should be in the same directory
641 >privoxy-index.html</TT
642 >, (i.e. one level up from
643 the manual directories).
651 > is designed for local preferences.
652 Make sure this does not get overwritten!
657 > Other configuration files should be installed as the new defaults,
658 but all previously installed configuration files should be preserved
659 as backups. This is just good manners :-)
664 > Please check platform specific notes in this doc, if you haven't
668 > packaging before for other platform
669 specific issues. Conversely, please add any notes that you know
670 are important for your platform (or contact one of the doc
671 maintainers to do this if you can't).
676 > Packagers should do a <SPAN
680 package after building it. So any previous installs should be
681 removed first to ensure the integrity of the newly built package.
682 Then run the package for a while to make sure there are no
683 obvious problems, before uploading.
695 NAME="NEWRELEASE-TARBALL">6.3.2. Source Tarball</H3
701 >make sure that you have freshly exported the right
702 version into an empty directory</I
704 >. (See "Building and releasing
705 packages" above). Then run:
715 CLASS="PROGRAMLISTING"
717 autoheader && autoconf && ./configure</PRE
734 CLASS="PROGRAMLISTING"
735 > make tarball-dist</PRE
742 > To upload the package to Sourceforge, simply issue
752 CLASS="PROGRAMLISTING"
753 > make tarball-upload</PRE
760 > Go to the displayed URL and release the file publicly on Sourceforge.
761 For the change log field, use the relevant section of the
773 NAME="NEWRELEASE-RPM">6.3.3. SuSE, Conectiva or Red Hat RPM</H3
775 > In following text, replace <TT
784 > for Red Hat or <SPAN
794 >make sure that you have freshly exported the right
795 version into an empty directory</I
797 >. (See "Building and releasing
801 > As the only exception to not changing anything after export from CVS,
802 now examine the file <TT
814 and make sure that the version information and the RPM release number are
815 correct. The RPM release numbers for each version start at one. Hence it must
816 be reset to one if this is the first RPM for
822 > which is built from version
825 HREF="http://sourceforge.net/project/showfiles.php?group_id=11118"
829 > if unsure. Else, it must be set to the highest already available RPM
830 release number for that version plus one.
843 CLASS="PROGRAMLISTING"
845 autoheader && autoconf && ./configure</PRE
862 CLASS="PROGRAMLISTING"
875 > To upload the package to Sourceforge, simply issue
885 CLASS="PROGRAMLISTING"
909 RPM release number as determined above.
910 Go to the displayed URL and release the file publicly on Sourceforge.
911 Use the release notes and change log from the source tarball package.
919 NAME="NEWRELEASE-OS2">6.3.4. OS/2</H3
925 >make sure that you have freshly exported the right
926 version into an empty directory</I
928 >. (See "Building and releasing
929 packages" above). Then get the OS/2 Setup module:
939 CLASS="PROGRAMLISTING"
940 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup</PRE
947 > You will need a mix of development tools.
948 The main compilation takes place with IBM Visual Age C++.
949 Some ancillary work takes place with GNU tools, available from
950 various sources like hobbes.nmsu.edu.
951 Specificially, you will need <TT
962 The packaging takes place with WarpIN, available from various sources, including
964 HREF="http://www.xworkplace.org/"
970 > Change directory to the <TT
974 Edit the os2build.cmd file to set the final executable filename.
985 CLASS="PROGRAMLISTING"
986 > installExeName='privoxyos2_setup_X.Y.Z.exe'</PRE
996 > file so the release number matches
1010 CLASS="PROGRAMLISTING"
1011 > PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"</PRE
1018 > You're now ready to build. Run:
1028 CLASS="PROGRAMLISTING"
1036 > You will find the WarpIN-installable executable in the
1040 > directory. Upload this anonymously to
1043 >uploads.sourceforge.net/incoming</TT
1045 for it, and you're done. Use the release notes and Change Log from the
1046 source tarball package.
1054 NAME="NEWRELEASE-SOLARIS">6.3.5. Solaris</H3
1056 > Login to Sourceforge's compilefarm via ssh:
1066 CLASS="PROGRAMLISTING"
1067 > ssh cf.sourceforge.net</PRE
1074 > Choose the right operating system (not the Debian one).
1075 When logged in, <SPAN
1079 >make sure that you have freshly exported the right
1080 version into an empty directory</I
1082 >. (See "Building and releasing
1083 packages" above). Then run:
1093 CLASS="PROGRAMLISTING"
1095 autoheader && autoconf && ./configure</PRE
1112 CLASS="PROGRAMLISTING"
1113 > gmake solaris-dist</PRE
1120 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1124 > on the Sourceforge machine (no ncftpput). You now have
1125 to manually upload the archive to Sourceforge's ftp server and release
1126 the file publicly. Use the release notes and Change Log from the
1127 source tarball package.
1135 NAME="NEWRELEASE-WINDOWS">6.3.6. Windows</H3
1137 > You should ensure you have the latest version of Cygwin (from
1139 HREF="http://www.cygwin.com/"
1141 >http://www.cygwin.com/</A
1143 Run the following commands from within a Cygwin bash shell.
1150 >make sure that you have freshly exported the right
1151 version into an empty directory</I
1153 >. (See "Building and releasing
1154 packages" above). Then get the Windows setup module:
1164 CLASS="PROGRAMLISTING"
1165 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup</PRE
1172 > Then you can build the package. This is fully automated, and is
1175 >winsetup/GNUmakefile</TT
1177 All you need to do is:
1187 CLASS="PROGRAMLISTING"
1196 > Now you can manually rename <TT
1198 >privoxy_setup.exe</TT
1202 >privoxy_setup_X_Y_Z.exe</TT
1204 SourceForge. When releasing the package on SourceForge, use the release notes
1205 and Change Log from the source tarball package.
1213 NAME="NEWRELEASE-DEBIAN">6.3.7. Debian</H3
1219 >make sure that you have freshly exported the
1220 right version into an empty directory</I
1223 "Building and releasing packages" above). Then add a log
1226 >debian/changelog</TT
1228 already there, for example by running:
1238 CLASS="PROGRAMLISTING"
1239 > debchange -v 3.1.1-alpha-1 "New upstream version"</PRE
1256 CLASS="PROGRAMLISTING"
1257 > dpkg-buildpackage -rfakeroot -us -uc -b</PRE
1267 >../privoxy_3.1.1-alpha-1_i386.deb</TT
1269 which can be uploaded. To upload the package to Sourceforge, simply
1280 CLASS="PROGRAMLISTING"
1281 > make debian-upload</PRE
1293 NAME="NEWRELEASE-MACOSX">6.3.8. Mac OSX</H3
1299 >make sure that you have freshly exported the right
1300 version into an empty directory</I
1302 >. (See "Building and releasing
1303 packages" above). Then get the Mac OSX setup module:
1313 CLASS="PROGRAMLISTING"
1314 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup</PRE
1331 CLASS="PROGRAMLISTING"
1354 Finally, it will copy over the necessary files to the ./osxsetup/files directory
1355 for further processing by <TT
1361 > Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
1362 name to match the release, and hit the "Create package" button.
1363 If you specify ./Privoxy.pkg as the output package name, you can then create
1364 the distributable zip file with the command:
1374 CLASS="PROGRAMLISTING"
1375 > zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg</PRE
1382 > You can then upload <TT
1384 >privoxyosx_setup_x.y.z.zip</TT
1388 >uploads.sourceforge.net/incoming</TT
1390 create a release for it, and you're done. Use the release notes
1391 and Change Log from the source tarball package.
1399 NAME="NEWRELEASE-FREEBSD">6.3.9. FreeBSD</H3
1401 > Login to Sourceforge's compile-farm via ssh:
1411 CLASS="PROGRAMLISTING"
1412 > ssh cf.sourceforge.net</PRE
1419 > Choose the right operating system.
1420 When logged in, <SPAN
1424 >make sure that you have freshly exported the right
1425 version into an empty directory</I
1427 >. (See "Building and releasing
1428 packages" above). Then run:
1438 CLASS="PROGRAMLISTING"
1440 autoheader && autoconf && ./configure</PRE
1457 CLASS="PROGRAMLISTING"
1458 > gmake freebsd-dist</PRE
1465 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1469 > on the Sourceforge machine (no ncftpput). You now have
1470 to manually upload the archive to Sourceforge's ftp server and release
1471 the file publicly. Use the release notes and Change Log from the
1472 source tarball package.
1480 NAME="NEWRELEASE-HPUX">6.3.10. HP-UX 11</H3
1486 >make sure that you have freshly exported the right
1487 version into an empty directory</I
1489 >. (See "Building and releasing
1490 packages" above). Then run:
1500 CLASS="PROGRAMLISTING"
1502 autoheader && autoconf && ./configure</PRE
1517 NAME="NEWRELEASE-AMIGA">6.3.11. Amiga OS</H3
1523 >make sure that you have freshly exported the right
1524 version into an empty directory</I
1526 >. (See "Building and releasing
1527 packages" above). Then run:
1537 CLASS="PROGRAMLISTING"
1539 autoheader && autoconf && ./configure</PRE
1554 NAME="NEWRELEASE-AIX">6.3.12. AIX</H3
1556 > Login to Sourceforge's compilefarm via ssh:
1566 CLASS="PROGRAMLISTING"
1567 > ssh cf.sourceforge.net</PRE
1574 > Choose the right operating system.
1575 When logged in, <SPAN
1579 >make sure that you have freshly exported the right
1580 version into an empty directory</I
1582 >. (See "Building and releasing
1583 packages" above). Then run:
1593 CLASS="PROGRAMLISTING"
1595 autoheader && autoconf && ./configure</PRE
1612 CLASS="PROGRAMLISTING"
1613 > make aix-dist</PRE
1620 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1624 > on the Sourceforge machine (no ncftpput). You now have
1625 to manually upload the archive to Sourceforge's ftp server and release
1626 the file publicly. Use the release notes and Change Log from the
1627 source tarball package.
1636 NAME="RELEASING">6.4. Uploading and Releasing Your Package</H2
1638 > After the package is ready, it is time to upload it
1639 to SourceForge, and go through the release steps. The upload
1649 HREF="ftp://upload.sourceforge.net/incoming"
1651 >ftp://upload.sourceforge.net/incoming</A
1667 >ijbswa-developers@lists.sourceforge.net</TT
1678 > targets as described above.
1681 > Once this done go to <A
1682 HREF="http://sourceforge.net/project/admin/editpackages.php?group_id=11118"
1684 >http://sourceforge.net/project/admin/editpackages.php?group_id=11118</A
1686 making sure you are logged in. Find your target platform in the
1687 second column, and click <TT
1691 then need to create a new release for your package, using the format
1694 >$VERSION ($CODE_STATUS)</TT
1705 > Now just follow the prompts. Be sure to add any appropriate Release
1706 notes. You should see your freshly uploaded packages in
1709 >"Step 2. Add Files To This Release"</SPAN
1711 appropriate box(es). Remember at each step to hit the
1714 >"Refresh/Submit"</SPAN
1715 > buttons! You should now see your
1716 file(s) listed in Step 3. Fill out the forms with the appropriate
1717 information for your platform, being sure to hit <SPAN
1721 for each file. If anyone is monitoring your platform, check the
1725 > box at the very bottom to notify them of
1726 the new package. This should do it!
1729 > If you have made errors, or need to make changes, you can go through
1730 essentially the same steps, but select <TT
1745 NAME="AFTERRELEASE">6.5. After the Release</H2
1747 > When all (or: most of the) packages have been uploaded and made available,
1748 send an email to the <A
1749 HREF="mailto:ijbswa-announce@lists.sourceforge.net"
1753 >, Subject: "Version X.Y.Z available for download". Be sure to
1756 HREF="http://sourceforge.net/project/showfiles.php?group_id=11118"
1760 >, the release notes and the Changelog. Also, post an
1761 updated News item on the project page Sourceforge, and update the Home
1762 page and docs linked from the Home page (see below).
1771 SUMMARY="Footer navigation table"
1800 HREF="webserver-update.html"
1810 >Testing Guidelines</TD
1820 >Update the Webserver</TD