4 >Releasing a New Version</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
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
39 >Privoxy Developer Manual</TH
60 HREF="webserver-update.html"
74 >6. Releasing a New Version</A
77 > When we release versions of <SPAN
81 our work leaves our cozy secret lab and has to work in the cold
82 RealWorld[tm]. Once it is released, there is no way to call it
83 back, so it is very important that great care is taken to ensure
84 that everything runs fine, and not to introduce problems in the
88 > So when releasing a new version, please adhere exactly to the
89 procedure outlined in this chapter.
92 > The following programs are required to follow this process:
103 > (GNU's version of make), autoconf, cvs.
110 NAME="VERSIONNUMBERS"
111 >6.1. Version numbers</A
114 > First you need to determine which version number the release will have.
118 > version numbers consist of three numbers,
119 separated by dots, like in X.Y.Z, where:
125 > X, the version major, is rarely ever changed. It is increased by one if
126 turning a development branch into stable substantially changes the functionality,
127 user interface or configuration syntax. Majors 1 and 2 were
131 >, and 3 will be the first stable
140 > Y, the version minor, represents the branch within the major version.
141 At any point in time, there are two branches being maintained:
142 The stable branch, with an even minor, say, 2N, in which no functionality is
143 being added and only bugfixes are made, and 2N+1, the development branch, in
144 which the further development of <SPAN
149 This enables us to turn the code upside down and inside out, while at the same time
150 providing and maintaining a stable version.
151 The minor is reset to zero (and one) when the major is inrcemented. When a development
152 branch has matured to the point where it can be turned into stable, the old stable branch
153 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
154 new stable branch 2N+2, and a new development branch 2N+3 is opened.
159 > Z, the point or sub version, represents a release of the software within a branch.
160 It is therefore incremented immediately before each code freeze.
161 In development branches, only the even point versions correspond to actual releases,
162 while the odd ones denote the evolving state of the sources on CVS in between.
163 It follows that Z is odd on CVS in development branches most of the time. There, it gets
164 increased to an even number immediately before a code freeze, and is increased to an odd
165 number again immediately thereafter.
166 This ensures that builds from CVS snapshots are easily distinguished from released versions.
167 The point version is reset to zero when the minor changes.
180 >6.2. Before the Release: Freeze</A
185 >must be done by one of the
187 > prior to each new release.
195 > Make sure that everybody who has worked on the code in the last
196 couple of days has had a chance to yell <SPAN
200 they have pending changes/fixes in their pipelines. Announce the
201 freeze so that nobody will interfere with last minute changes.
206 > Increment the version number (point from odd to even in development
218 > has changed since last
219 release (i.e. software release or standalone actions file release),
220 bump up its version info to A.B in this line:
231 CLASS="PROGRAMLISTING"
232 > {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}</PRE
240 Then change the version info in doc/webserver/actions/index.php,
241 line: '$required_actions_file_version = "A.B";'
246 > If the HTML documentation is not in sync with the SGML sources
247 you need to regenerate and upload it to the webserver. (If in
248 doubt, just do it.) See the Section "Updating the webserver" in
249 this manual for details.
256 >Commit all files that were changed in the above steps!</I
262 > Tag all files in CVS with the version number with
270 Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
275 > If the release was in a development branch, increase the point version
276 from even to odd (X.Y.(Z+1)) again in <TT
285 > On the webserver, copy the user manual to a new top-level directory
289 >. This ensures that help links from the CGI
290 pages, which have the version as a prefix, will go into the right version of the manual.
291 If this is a development branch release, also symlink <TT
318 >6.3. Building and Releasing the Packages</A
321 > Now the individual packages can be built and released. Note that for
322 GPL reasons the first package to be released is always the source tarball.
328 > types of packages, including the source tarball,
331 >you must make sure that you build from clean sources by exporting
332 the right version from CVS into an empty directory:</I
343 CLASS="PROGRAMLISTING"
344 > mkdir dist # delete or choose different name if it already exists
346 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
347 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current</PRE
357 > a single bit, including, but not limited to
358 version information after export from CVS. This is to make sure that
359 all release packages, and with them, all future bug reports, are based
360 on exactly the same code.
363 > Please find additional instructions for the source tarball and the
364 individual platform dependent binary packages below. And details
365 on the Sourceforge release process below that.
372 NAME="PACK-GUIDELINES"
373 >6.3.1. Note on Privoxy Packaging</A
376 > Please keep these general guidelines in mind when putting together
377 your package. These apply to <I
395 write access to: all <TT
399 logfiles, and the <TT
403 need to determine the best way to do this for your platform.
408 > Please include up to date documentation. At a bare minimum:
420 > (toplevel directory)
437 > (toplevel directory)
454 > (toplevel directory)
471 > (toplevel directory, Unix-like
489 > (doc/webserver/user-manual/)
506 > (doc/webserver/faq/)
514 > Also suggested: <TT
516 >Developer Manual</TT
518 (doc/webserver/devel-manual) and <TT
522 (toplevel directory). <TT
525 > and the manuals are
526 HTML docs. There are also text versions in
530 > which could conceivably also be
534 > The documentation has been designed such that the manuals are linked
535 to each other from parallel directories, and should be packaged
539 > can also be included and
540 can serve as a focal point for docs and other links of interest.
541 This should be one level up from the manuals. There are two
542 css stylesheets that can be included for better presentation:
550 These should be in the same directory with
554 >, (i.e. one level up from the manual
563 > is designed for local preferences.
564 Make sure this does not get overwritten!
569 > Other configuration files should be installed as the new defaults,
570 but all previously installed configuration files should be preserved
571 as backups. This is just good manners :-)
576 > Please check platform specific notes in this doc, if you haven't
580 > packaging before for other platform
581 specific issues. Conversely, please add any notes that you know
582 are important for your platform (or contact one of the doc
583 maintainers to do this if you can't).
595 NAME="NEWRELEASE-TARBALL"
596 >6.3.2. Source Tarball</A
601 >make sure that you have freshly exported the right
602 version into an empty directory</I
603 >. (See "Building and releasing
604 packages" above). Then run:
614 CLASS="PROGRAMLISTING"
616 autoheader && autoconf && ./configure</PRE
633 CLASS="PROGRAMLISTING"
634 > make tarball-dist</PRE
641 > To upload the package to Sourceforge, simply issue
651 CLASS="PROGRAMLISTING"
652 > make tarball-upload</PRE
659 > Go to the displayed URL and release the file publicly on Sourceforge.
660 For the change log field, use the relevant section of the
672 NAME="NEWRELEASE-RPM"
673 >6.3.3. SuSE, Conectiva or Red Hat RPM</A
676 > In following text, replace <TT
685 > for Red Hat or <SPAN
693 >make sure that you have freshly exported the right
694 version into an empty directory</I
695 >. (See "Building and releasing
699 > As the only exception to not changing anything after export from CVS,
700 now examine the file <TT
712 and make sure that the version information and the RPM release number are
713 correct. The RPM release numbers for each version start at one. Hence it must
714 be reset to one if this is the first RPM for
720 > which is built from version
723 HREF="http://sourceforge.net/project/showfiles.php?group_id=11118"
727 > if unsure. Else, it must be set to the highest already available RPM
728 release number for that version plus one.
741 CLASS="PROGRAMLISTING"
743 autoheader && autoconf && ./configure</PRE
760 CLASS="PROGRAMLISTING"
773 > To upload the package to Sourceforge, simply issue
783 CLASS="PROGRAMLISTING"
807 RPM release number as determined above.
808 Go to the displayed URL and release the file publicly on Sourceforge.
809 Use the release notes and change log from the source tarball package.
817 NAME="NEWRELEASE-OS2"
823 >make sure that you have freshly exported the right
824 version into an empty directory</I
825 >. (See "Building and releasing
826 packages" above). Then get the OS/2 Setup module:
836 CLASS="PROGRAMLISTING"
837 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup</PRE
844 > You will need a mix of development tools.
845 The main compilation takes place with IBM Visual Age C++.
846 Some ancillary work takes place with GNU tools, available from
847 various sources like hobbes.nmsu.edu.
848 Specificially, you will need <TT
859 The packaging takes place with WarpIN, available from various sources, including
861 HREF="http://www.xworkplace.org/"
867 > Change directory to the <TT
871 Edit the os2build.cmd file to set the final executable filename.
882 CLASS="PROGRAMLISTING"
883 > installExeName='privoxyos2_setup_X.Y.Z.exe'</PRE
893 > file so the release number matches
907 CLASS="PROGRAMLISTING"
908 > PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"</PRE
915 > You're now ready to build. Run:
925 CLASS="PROGRAMLISTING"
933 > You will find the WarpIN-installable executable in the
937 > directory. Upload this anonymously to
940 >uploads.sourceforge.net/incoming</TT
942 for it, and you're done. Use the release notes and Change Log from the
943 source tarball package.
951 NAME="NEWRELEASE-SOLARIS"
955 > Login to Sourceforge's compilefarm via ssh:
965 CLASS="PROGRAMLISTING"
966 > ssh cf.sourceforge.net</PRE
973 > Choose the right operating system (not the Debian one).
976 >make sure that you have freshly exported the right
977 version into an empty directory</I
978 >. (See "Building and releasing
979 packages" above). Then run:
989 CLASS="PROGRAMLISTING"
991 autoheader && autoconf && ./configure</PRE
1008 CLASS="PROGRAMLISTING"
1009 > gmake solaris-dist</PRE
1016 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1020 > on the Sourceforge machine (no ncftpput). You now have
1021 to manually upload the archive to Sourceforge's ftp server and release
1022 the file publicly. Use the release notes and Change Log from the
1023 source tarball package.
1031 NAME="NEWRELEASE-WINDOWS"
1035 > You should ensure you have the latest version of Cygwin (from
1037 HREF="http://www.cygwin.com/"
1039 >http://www.cygwin.com/</A
1041 Run the following commands from within a Cygwin bash shell.
1046 >make sure that you have freshly exported the right
1047 version into an empty directory</I
1048 >. (See "Building and releasing
1049 packages" above). Then get the Windows setup module:
1059 CLASS="PROGRAMLISTING"
1060 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup</PRE
1067 > Then you can build the package. This is fully automated, and is
1070 >winsetup/GNUmakefile</TT
1072 All you need to do is:
1082 CLASS="PROGRAMLISTING"
1091 > Now you can manually rename <TT
1093 >privoxy_setup.exe</TT
1097 >privoxy_setup_X_Y_Z.exe</TT
1099 SourceForge. When releasing the package on SourceForge, use the release notes
1100 and Change Log from the source tarball package.
1108 NAME="NEWRELEASE-DEBIAN"
1114 >make sure that you have freshly exported the right
1115 version into an empty directory</I
1116 >. (See "Building and releasing
1117 packages" above). Then, run:
1127 CLASS="PROGRAMLISTING"
1129 autoheader && autoconf && ./configure</PRE
1144 NAME="NEWRELEASE-MACOSX"
1150 >make sure that you have freshly exported the right
1151 version into an empty directory</I
1152 >. (See "Building and releasing
1153 packages" above). Then get the Mac OSX setup module:
1163 CLASS="PROGRAMLISTING"
1164 > cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup</PRE
1181 CLASS="PROGRAMLISTING"
1204 Finally, it will copy over the necessary files to the ./osxsetup/files directory
1205 for further processing by <TT
1211 > Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
1212 name to match the release, and hit the "Create package" button.
1213 If you specify ./Privoxy.pkg as the output package name, you can then create
1214 the distributable zip file with the command:
1224 CLASS="PROGRAMLISTING"
1225 >zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg</PRE
1232 > You can then upload <TT
1234 >privoxyosx_setup_x.y.z.zip</TT
1238 >uploads.sourceforge.net/incoming</TT
1240 create a release for it, and you're done. Use the release notes
1241 and Change Log from the source tarball package.
1249 NAME="NEWRELEASE-FREEBSD"
1253 > Login to Sourceforge's compilefarm via ssh:
1263 CLASS="PROGRAMLISTING"
1264 > ssh cf.sourceforge.net</PRE
1271 > Choose the right operating system.
1274 >make sure that you have freshly exported the right
1275 version into an empty directory</I
1276 >. (See "Building and releasing
1277 packages" above). Then run:
1287 CLASS="PROGRAMLISTING"
1289 autoheader && autoconf && ./configure</PRE
1306 CLASS="PROGRAMLISTING"
1307 > gmake freebsd-dist</PRE
1314 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1318 > on the Sourceforge machine (no ncftpput). You now have
1319 to manually upload the archive to Sourceforge's ftp server and release
1320 the file publicly. Use the release notes and Change Log from the
1321 source tarball package.
1329 NAME="NEWRELEASE-HPUX"
1330 >6.3.10. HP-UX 11</A
1335 >make sure that you have freshly exported the right
1336 version into an empty directory</I
1337 >. (See "Building and releasing
1338 packages" above). Then run:
1348 CLASS="PROGRAMLISTING"
1350 autoheader && autoconf && ./configure</PRE
1365 NAME="NEWRELEASE-AMIGA"
1366 >6.3.11. Amiga OS</A
1371 >make sure that you have freshly exported the right
1372 version into an empty directory</I
1373 >. (See "Building and releasing
1374 packages" above). Then run:
1384 CLASS="PROGRAMLISTING"
1386 autoheader && autoconf && ./configure</PRE
1401 NAME="NEWRELEASE-AIX"
1405 > Login to Sourceforge's compilefarm via ssh:
1415 CLASS="PROGRAMLISTING"
1416 > ssh cf.sourceforge.net</PRE
1423 > Choose the right operating system.
1426 >make sure that you have freshly exported the right
1427 version into an empty directory</I
1428 >. (See "Building and releasing
1429 packages" above). Then run:
1439 CLASS="PROGRAMLISTING"
1441 autoheader && autoconf && ./configure</PRE
1458 CLASS="PROGRAMLISTING"
1459 > make aix-dist</PRE
1466 > which creates a gzip'ed tar archive. Sadly, you cannot use <B
1470 > on the Sourceforge machine (no ncftpput). You now have
1471 to manually upload the archive to Sourceforge's ftp server and release
1472 the file publicly. Use the release notes and Change Log from the
1473 source tarball package.
1483 >6.4. Uploading and Releasing Your Package</A
1486 > After the package is ready, it is time to upload it
1487 to SourceForge, and go through the release steps. The upload
1497 HREF="ftp://upload.sourceforge.net/incoming"
1499 >ftp://upload.sourceforge.net/incoming</A
1515 >ijbswa-developers@lists.sourceforge.net</TT
1526 > targets as described above.
1529 > Once this done go to <A
1530 HREF="http://sourceforge.net/project/admin/editpackages.php?group_id=11118"
1532 >http://sourceforge.net/project/admin/editpackages.php?group_id=11118</A
1534 making sure you are logged in. Find your target platform in the
1535 second column, and click <TT
1539 then need to create a new release for your package, using the format
1542 >$VERSION ($CODE_STATUS)</TT
1550 > Now just follow the prompts. Be sure to add any appropriate Release
1551 notes. You should see your freshly uploaded packages in
1554 >"Step 2. Add Files To This Release"</SPAN
1556 appropriate box(es). Remember at each step to hit the
1559 >"Refresh/Submit"</SPAN
1560 > buttons! You should now see your
1561 file(s) listed in Step 3. Fill out the forms with the appropriate
1562 information for your platform, being sure to hit <SPAN
1566 for each file. If anyone is monitoring your platform, check the
1570 > box at the very bottom to notify them of
1571 the new package. This should do it!
1574 > If you have made errors, or need to make changes, you can go through
1575 essentially the same steps, but select <TT
1591 >6.5. After the Release</A
1594 > When all (or: most of the) packages have been uploaded and made available,
1595 send an email to the <A
1596 HREF="mailto:ijbswa-announce@lists.sourceforge.net"
1600 >, Subject: "Version X.Y.Z available for download". Be sure to
1603 HREF="http://sourceforge.net/project/showfiles.php?group_id=11118"
1607 >, the release notes and the change log.
1642 HREF="webserver-update.html"
1651 >Testing Guidelines</TD
1661 >Update the Webserver</TD