X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fnewrelease.html;h=7b01ecf5228de262e6b6d3aceaf0d57f34fba6a2;hp=fa80e1f455ecdcc71d5aae097b0a8a13bee71238;hb=6d810395712f0337682205c4ea304009c86c128f;hpb=5700aead3098beb0cc5a02bc0034a0d4194774a6 diff --git a/doc/webserver/developer-manual/newrelease.html b/doc/webserver/developer-manual/newrelease.html index fa80e1f4..7b01ecf5 100644 --- a/doc/webserver/developer-manual/newrelease.html +++ b/doc/webserver/developer-manual/newrelease.html @@ -1,1956 +1,1282 @@ - -
When we release versions of Privoxy, + + +
+ ++ 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 + 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.) -
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: -
-
{+add-header{X-Actions-File-Version: A.B} -filter -no-popups} |
- Then change the version info in doc/webserver/actions/index.php, - line: '$required_actions_file_version = "A.B";' -
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! -
Tag all files in CVS with the version number with - "cvs tag v_X_Y_Z". - Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. -
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. -
On the webserver, copy the user manual to a new top-level directory - called X.Y.Z. This ensures that help links from the CGI - pages, which have the version as a prefix, will go into the right version of the manual. - If this is a development branch release, also symlink X.Y.(Z-1) - to X.Y.Z and X.Y.(Z+1) to - . (i.e. dot). -
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): -
mkdir dist # delete or choose different name if it already exists + ++ |
+
+ 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. +
++ 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 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. +
++ 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 + 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. +
++ 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. +
++ 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: +
++
+
++ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup ++ |
+
+ Then you can build the package. This is fully automated, and is + controlled by winsetup/GNUmakefile. All + you need to do is: +
++
+
++ cd winsetup + make ++ |
+
+ 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. +
++ 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.18-UNRELEASED-1 "New upstream version" ++ |
+
+ Then, run: +
++
+
++ dpkg-buildpackage -rfakeroot -us -uc -b ++ |
+
+ This will create ../privoxy_3.0.18-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). Then get the Mac OS X setup module: +
++
+
++ 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 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. +
++ Login to Sourceforge's compile-farm via ssh: +
++
+
++ ssh cf.sourceforge.net ++ |
+
+ 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: +
++
+
++ cd current + autoheader && autoconf && ./configure ++ |
+
+ Then run: +
++
+
++ gmake freebsd-dist ++ |
+
+ 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. +
++ 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 FIXME. +
++ 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 FIXME. +
++ Login to Sourceforge's compilefarm via ssh: +
++
+
++ ssh cf.sourceforge.net ++ |
+
+ 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: +
++
+
++ cd current + autoheader && autoconf && ./configure ++ |
+
+ Then run: +
++
+
++ make aix-dist ++ |
+
+ which creates a gzip'ed tar archive. Sadly, you cannot use make aix-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. +
++ 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.18 + (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. +
+