How to build a release of Apache - The Apache HTTP Server Project

Alexei Kosut <akosut@apache.org>
Ralf S. Engelschall <rse@apache.org>
Jim Jagielski <jim@apache.org>
Ken Coar <coar@apache.org>
Martin Kraemer <martin@apache.org>

This document has been obsoleted in httpd-2.0 by the build/httpd_roll_release script. It does everything for you. At some point, we may come back and update this document. So, in the meantime, ignore this and use that script for Apache 2.0 rolls.

This document describes the typical release cycle the release manager has to step through when creating a new Apache release. It is written down as a step-by-step instruction list and should be followed exactly as specified to avoid problems or inconsistencies both in the created tarballs and the source repository.

How to build an Apache Unix release

Note: The below assumes that you are using ssh to login to your httpd.apache.org account. If you are "rolling the tarball" remotely, the differences will be noted.

Important: Once tagged and the tarball is rolled, there is no going back. If there are problems with the tarball, the version number (either the rev-level or beta-level) must be bumped resulting in a new tag, tarball and release.

Checkout the Apache source if needed into a scratch directory:
$ cvs checkout -P apache-1.X
Note that the current httpd-docs-1.3/htdocs documentation tree is automatically extracted into apache-1.X/htdocs/ (two macros in the cvs configuration file /home/cvs/CVSROOT/modules do that for you).
For Apache 2.X:
$ cvs checkout -r APACHE_2_X_BRANCH -Pd httpd-2.X httpd-2.0
$ cd httpd-2.X/srclib
$ cvs checkout apr apr-util
Omit the -r APACHE_2_X_BRANCH flag for the current development branch (e.g. 2.1-dev.) The current development branch always sits at cvs HEAD.

cd into the apache CVS tree.
$ cd apache-1.X
or
$ cd httpd-2.X

Adjust Announcement to taste.

A prototype Announcement is included in the main CVS source tree. This file should be updated to reflect the current state of affairs concerning the release. For example, the Release Version should reflect what is actually being announced. Also, the key enhancements of the Release should be noted.
$ vi Announcement
$ cvs commit Announcement

Note: This document is also present in the httpd-dist cvs module, both in HTML and plain text form. You may want to create one version out of the other.

Change the version number to indicate a release.

For Apache 1.3
Change SERVER_BASEREVISION in src/include/httpd.h from ``Apache/1.X.Y-dev'' to ``Apache/1.X.Y''. Then also change APACHE_RELEASE in the same file from ``1XXYY000'' to ``1XXYY100''. The format is something like printf("%d%02d%02d%d%02d", major, minor, bugfix, final, beta).
$ vi src/include/httpd.h
$ cvs commit src/include/httpd.h

For Apache 2.0:
Change SERVER_BASEREVISION in include/httpd.h from ``2.X-dev'' to ``2.X''. Then also change APACHE_RELEASE in the same file from ``2XXYY000'' to ``2XXYY100''.

Note: until Apache 2.0 is of general release quality, module magic numbers are not enforced. You must edit include/ap_mmn.h and bump the MODULE_MAGIC_NUMBER_MAJOR prior to rolling the tarball, to assure beta testers are testing the corresponding .so modules. This policy will be retracted, and coders will be reponsible for mmn bumps, once Apache 2.0 is officially released.

Make sure your PGP keys are already present in the KEYS file. If they are not, extract your public key using the ``pgp -kxa'' command, add them to the KEYS file and commit it before tagging.

Tag the sources for this release:
(note: be sure to tag the whole thing, not just src!)
$ cvs tag APACHE_1_X_Y
For Apache 2.0:
$ cvs tag APACHE_2_X_Y

Make an export version of the distribution: (this creates a second subdirectory apache-Z.X.Y for the exported version beside the existing CVS tree in apache-Z.X)

For Apache 1.3:
$ cd ..
$ umask 022
$ cvs export -r APACHE_1_X_Y -d apache_1.X.Y apache-1.X
$ cd apache_1.X.Y
Again, the current httpd-docs-1.3/htdocs documentation tree is automatically extracted into apache-1.X.Y/htdocs/ for you.

Note: There is a known problem using cvs export remotely with cvs-1.9 and later. If this affects you, you will need to do a checkout instead:
$ umask 022
$ cvs checkout -r APACHE_1_X_Y -d apache_1.X.Y apache-1.X
$ cd apache_1.X.Y
$ cvs checkout -r APACHE_1X_Y -d htdocs httpd-docs-1.3/htdocs

For Apache 2.0:
$ cd ..
$ umask 022
$ cvs export -r APACHE_2_X_Y -d apache_2.X.Y httpd-2.X
$ cd apache_2.X.Y/srclib
$ cvs export -r APACHE_2_X_Y apr apr-util

Note: There is a known problem using cvs export remotely with cvs-1.9 and later. If this affects you, you will need to do a checkout instead:
$ umask 022
$ cvs checkout -r APACHE_2_X_Y -d apache_2.X.Y httpd-2.X
$ cd apache_2.X.Y/srclib
$ cvs checkout -r APACHE_2X_Y apr apr-util

Make sure the master site's FAQ is up-to-date:
$ (cd /www/httpd.apache.org/docs/misc ; cvs update)

Extract the FAQ as a single file, as it appears on the Web:
$ links -source http://httpd.apache.org/docs/misc/FAQ.html > htdocs/manual/misc/FAQ.html

Create the configuration files:

For Apache 1.3:
Create src/Configuration file:
$ cp src/Configuration.tmpl src/Configuration

For Apache 2.0:
Create ./configure file, and remove all symlinks
$ ./buildconf
$ rm -f ltconfig ltmain.sh config.sub config.guess
$ cp /usr/local/share/libtool/ltconfig .
$ cp /usr/local/share/libtool/ltmain.sh .
$ cp /usr/local/share/libtool/config.sub .
$ cp /usr/local/share/libtool/config.guess .

Remove STATUS, RULES.CVS, src/INDENT, the multi-part FAQ, various .cvsignore and the developer's test subdirectories. Depending on which version you are releasing, not all of these files will be in the repository:
$ rm STATUS RULES.CVS src/INDENT htdocs/manual/misc/FAQ-*.html
$ find . -name ".cvsignore" -exec rm {} \;
$ find . -type d -name "test" -exec rm -Rf {} \;

Note: If you needed to do a checkout instead of a export, you will also need to remove the CVS administrative files:
$ find . -type d -name "CVS" -exec rm -rf {} \;

Expand the Server-Side-Include directives in the manual:
$ cd htdocs/manual
$ ./expand.pl
$ rm ./expand.pl
$ cd ../../..

Roll the distribution tarball:
$ tar cvf apache_Z.X.Y.tar apache_Z.X.Y

Make the final packed distribution files:
$ cp -p apache_Z.X.Y.tar xapache_Z.X.Y.tar
$ gzip -9 apache_Z.X.Y.tar
$ mv xapache_Z.X.Y.tar apache_Z.X.Y.tar
$ compress apache_Z.X.Y.tar

Test the packed tar files and check for errors:
$ gunzip -c apache_Z.X.Y.tar.gz | tar tvf -
(or simply: $ tar tvzf apache_Z.X.Y.tar.gz)
$ uncompress <apache_Z.X.Y.tar.Z | tar tvf -

Sign the distribution files:
$ pgp -sba apache_Z.X.Y.tar.gz
$ pgp -sba apache_Z.X.Y.tar.Z

Note: Be sure your PGP key is already in the KEYS file!

Test the tarball signatures:
$ pgp apache_Z.X.Y.tar.gz.asc apache_Z.X.Y.tar.gz
$ pgp apache_Z.X.Y.tar.Z.asc apache_Z.X.Y.tar.Z

Remember the CHANGES file:
$ cp apache_Z.X.Y/src/CHANGES ./CHANGES_Z.X

Cleanup:
(this deletes the export tree: it is now no longer required. We still need the CVS tree, see below)
$ rm -fr apache_Z.X.Y

Make the tarball available for testing purposes (in http://httpd.apache.org/dev/dist/):
$ chmod 664 CHANGES_Z.X apache_Z.X.Y.tar.*
$ cp -pv apache_Z.X.Y.tar.gz /www/httpd.apache.org/dev/dist/
$ cp -pv apache_Z.X.Y.tar.gz.asc /www/httpd.apache.org/dev/dist/
$ cp -pv apache_Z.X.Y.tar.Z /www/httpd.apache.org/dev/dist/
$ cp -pv apache_Z.X.Y.tar.Z.asc /www/httpd.apache.org/dev/dist/
$ chmod g+w /www/httpd.apache.org/dev/dist/apache_Z.X.Y.tar.*

Note: If rolling the tarball remotely, you should use scp to place them in httpd.apache.org in the /www/httpd.apache.org/dev/dist/ directory.

Bump the version number to the next version and indicate we are in development.
cd back into the CVS tree location.
$ cd apache-Z.X
For Apache 1.3:
Change SERVER_BASEREVISION in src/include/httpd.h from ``Apache/1.X.Y'' to ``Apache/1.X.(Y+1)-dev'' and change APACHE_RELEASE to 1XX(YY+1)000.
(1.3.x only) Additionally make sure that the Configure script's version knowledge for the SHARED_CORE reflects the new version.revision.patchlevel triple. Look for the line ``V=1 R=X P=Y'' inside src/Configure and adjust it accordingly.
Finally, add a new line ``Changes with Apache 1.X.(Y+1):'' to the head of the src/CHANGES file for the forthcoming fixes in the new version.
$ vi src/include/httpd.h \ src/Configure \ src/CHANGES
$ cvs commit src/include/httpd.h \ src/Configure \ src/CHANGES

Edit the STATUS file and update the status for the tagged apache_1.X.Y version, and add a header line for the new apache_1.X.(Y+1) version
$ vi STATUS
$ cvs commit STATUS

$ cd ..

For Apache 2.0:
Change SERVER_BASEREVERSION in include/httpd.h from ``2.X.Y'' to ``2.X.(Y+1)-dev'' and change APACHE_RELEASE to 1XX(YY+1)000.
Finally, add a new line ``Changes with Apache 1.X.(Y+1):'' to the head of the CHANGES file for the forthcoming fixes in the new version.
$ vi include/httpd.h \ CHANGES
$ cvs commit include/httpd.h \ CHANGES
$ cd ..

Cleanup:
(delete the CVS tree, after verification that it does not contain any uncommitted changes)
$ cvs release -d apache-Z.X

Now wait for the group to test and approve the tarball.

Final release steps

Note: Do not continue with the rest of these instructions until the group really approves the tarball!

Make the distribution available (in http://www.apache.org/dist/httpd/) Z is either 1 or 2:
$ cp CHANGES_Z.X /www/www.apache.org/dist/httpd/CHANGES_Z.X
$ cp apache_Z.X.Y.tar.gz /www/www.apache.org/dist/httpd/
$ cp apache_Z.X.Y.tar.gz.asc /www/www.apache.org/dist/httpd/
$ cp apache_Z.X.Y.tar.Z /www/www.apache.org/dist/httpd/
$ cp apache_Z.X.Y.tar.Z.asc /www/www.apache.org/dist/httpd/

Note: If rolling the tarball remotely, you should use scp to place them in www.apache.org in the /www/www.apache.org/dist/httpd/ directory.

If the Win32 binary is already built and tested at this point, you can add it to the dist directory as well as to the binaries/win32/ directory.

Checkout the httpd-dist site, if needed, into a scratch directory:
$ cvs -d cvs.apache.org:/home/cvs checkout -P httpd-dist

Change directory into httpd-dist
$ cd httpd-dist/

Edit the files README.html and HEADER.html as well as Announcement.html and its plaintext equivalent Announcement.txt plus the .htaccess file (which defines the AddDescription comments) from the httpd-dist CVS tree as required (all in the . subdirectory). The Announcement.* files should be based on the Announcement file in the tagged CVS tree. For Apache 2.0, Announcement should be replaced with Announcement2:
$ vi README.html HEADER.html Announcement.html Announcement.txt .htaccess

Commit the changes:
$ cvs commit README.html HEADER.html Announcement.html Announcement.txt .htaccess
$ cd ../..

Checkout the httpd site if needed into a scratch directory:
$ cvs -d cvs.apache.org:/home/cvs checkout httpd-site

cd into the httpd-site xdocs tree.
$ cd httpd-site/xdocs/

Edit the index.xml page from the httpd-site CVS tree as required:
$ vi index.xml

Commit the changes:
$ cd ..
$ ./build.sh # Check result before continuing
$ cvs commit

Update the checked-out versions of the httpd-dist documents for the web server:
$ umask 002
$ cd /www/www.apache.org/dist/httpd/
$ cvs update -dP

Create an empty directory for future patches:
$ mkdir patches/apply_to_1.X.Y

Update the checked-out version of the httpd-site index.html page for the web server:
$ umask 002
$ cd /www/httpd.apache.org/
$ cvs update -dP

At this point, the web-sites reflect the existance of the new release.

As it is going to be some 24hrs before any announcement goes out (to make sure that the mirror's have at least a chance of grabbing a copy) this is also the right time to mail dev@httpd.apache.org and ask people to upload and move into position any binaries they have build and vetted.

See how to build a release of Apache for Windows.

Announcing a New Release

Once a release is built and released, it is time to announce it to the world.

Grab the prepared Announcement:

You can grab either the Announcement file in the tagged tree, or the Announcement.txt file from the web-site.

Post the Announcement:

Once the tarball is built, give the mirrors a good 24 hours to get up to sync. This is really important if this this a final (i.e.: non-beta) release.

Now, Announcement should be posted to the following places (please note that a mail send to announce@apache.org must have your apache.org address set as its 'From' address, otherwise it won't pass the anti-spam filter):

Unmoderated UseNet newsgroups (should be crossposted)

comp.infosystems.www.servers.unix

comp.infosystems.www.servers.ms-windows

comp.infosystems.www.servers.misc

de.comm.infosystems.www.servers

Moderated UseNet newsgroups (do not crosspost)

comp.infosystems.www.announce

Mailing Lists

announce@apache.org

announce@httpd.apache.org

users@httpd.apache.org

users-de@httpd.apache.org

Make sure that Announcement.txt and Announcement.html in httpd-dist are updated to include these changes.

Bask in the glow