How to build a release of Apache

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 dev.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.

---

1. 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.0:
   $ cvs checkout -P httpd-2.X
$ cd httpd-2.X/srclib
$ cvs checkout apr apr-util

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

   [ Adjusting Announcement to taste ]
   

3. • 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 apache-site/dist/ directory, both in HTML and plain text form. You may want to create one version out of the other.

   ---

   [ Only for final releases, not for internal pre-releases ]
   

4. 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.

5. 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.

6. 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

   ---

   [ For all releases ]
   

7. 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

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

9. 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

10. For Apache 1.3:
    Create src/Configuration file: (1.3.x only)
    $ 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 .
    

11. 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 {} \;

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

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

14. 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
    

15. 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 -
    

16. 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!
      

17. 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
    

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

19. 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

20. Make the tarball available for testing purposes (in http://dev.apache.org/dist/):
    $ chmod 664 CHANGES_Z.X apache_Z.X.Y.tar.*
$ cp -pv apache_Z.X.Y.tar.gz /www/dev.apache.org/dist/
$ cp -pv apache_Z.X.Y.tar.gz.asc /www/dev.apache.org/dist/
$ cp -pv apache_Z.X.Y.tar.Z /www/dev.apache.org/dist/
$ cp -pv apache_Z.X.Y.tar.Z.asc /www/dev.apache.org/dist/
$ chmod g+w /www/dev.apache.org/dist/apache_Z.X.Y.tar.*
    
    • Note: If rolling the tarball remotely, you should use scp to place them in dev.apache.org in the /www/dev.apache.org/dist directory.

    ---

    [ Only for final releases, not for internal pre-releases ]
    

21. cd back into the CVS tree location.
    $ cd apache-Z.X

22. 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 \
     src/CHANGES
$ cvs commit include/httpd.h \
     CHANGES
$ cd ..
    

    ---

23. 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 after the group has approved the tarball ]
    

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

24. Make the distribution available (in http://www.apache.org/dist/) Z is either 1 or 2:
    $ cp CHANGES_Z.X /www/www.apache.org/dist/CHANGES_Z.X
$ cp apache_Z.X.Y.tar.gz /www/www.apache.org/dist
$ cp apache_Z.X.Y.tar.gz.asc /www/www.apache.org/dist
$ cp apache_Z.X.Y.tar.Z /www/www.apache.org/dist
$ cp apache_Z.X.Y.tar.Z.asc /www/www.apache.org/dist
    
    • Note: If rolling the tarball remotely, you should use scp to place them in dev.apache.org in the /www/apache.org/dist/ 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.

25. Checkout the Apache site if needed into a scratch directory:
    $ cvs checkout apache-site

26. cd into the apache-site CVS tree.
    $ cd apache-site/dist/

27. 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 apache-site CVS tree as required (all in the ./dist 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
    

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

29. Checkout the httpd site if needed into a scratch directory:
    $ cvs checkout httpd-site

30. cd into the httpd-site CVS tree.
    $ cd httpd-site/

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

32. Commit the changes:
    $ cvs commit index.html
    

33. Update the checked-out versions of the apache-site documents for the web server:
    $ umask 002
$ cd /www/www.apache.org/dist/
$ cvs update README.html \
     HEADER.html \
     Announcement.html \
     Announcement.txt \
     .htaccess

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

35. 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 index.html

36. 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.