Documentation

The Apache documentation needs to be updated for some patches, most often for enhancements. You may wish to see if your patch is considered generally acceptable before updating the documentation. Patches for the documentation are submitted with any code changes in the same patch format.

Please note that for Apache 2.0 and above, most of the documentation is generated from XML. Changes are made to the XML form and the html form is built. See http://httpd.apache.org/docs-project/docsformat.html for more information.

Choosing a level of base code for comparison

Currently, there are three active Apache httpd source trees:

  • Apache httpd 1.3 (apache-1.3 main branch in cvs)
  • Apache httpd 2.0.x (httpd-2.0, APACHE_2_0_BRANCH branch in cvs)
  • Apache httpd 2.1.x (httpd-2.1 main branch in cvs)

    A patch should be created against the last public release or, if practical, the latest code in CVS for the relevant source tree.

    Instructions for obtaining a source tree from CVS are at http://httpd.apache.org/dev/anoncvs.txt

    .

    Here are instructions for easily obtaining diffs without using CVS:

    [download httpd-2.0.48.tar.gz to /usr/local/src]

cd /usr/local/src
tar xvzf httpd-2.0.48.tar.gz
cp -ax httpd-2.0.48 httpd-2.0.48.new

[edit files in httpd-2.0.48.new/ and then test, test, test]

cd /usr/local/src
diff -ru httpd-2.0.48 httpd-2.0.48.new > my.unified.diff.patch

    Submitting your Patch

    Traditionally, patches have been submitted on the developer's mailing list as well as through the bug database. Unfortunately, this has made it hard to easily track the patches. And without being able to easily track them, too many of them have been ignored.

    Patches must now be submitted through the bug database, at http://nagoya.apache.org/bugzilla/ . You'll need to create a Bugzilla account there if you don't already have one. Submit the patch by first entering a new bug report. Be sure to specify APR for the product if the patch is for a file in srclib/apr or srclib/apr-util. The following information is very helpful, when it is available:

  • for Apache httpd 2.0.x bugs, mention whether or not it occurred with Apache httpd 1.3
  • explain how to reproduce the problem and how the patch has been tested

    After the bug report has been created, edit it again and specify PatchAvailable as a keyword and then add your patch as a new attachment.

    If you need to discuss the patch on the developer's mailing list, make sure that the Bugzilla PR number appears in the subject.

    Be aware that the core developers tend to be very conservative about what makes it into the core of Apache. Apache has a very flexible API, and any advanced functionality is likely to be pushed to be a third-party module. Portability fixes are the most important; protocol correctness is also critical for us; and we're sure there's more dumb mistakes in the code than we could shake a stick at. Those will get priority; new functionality may not. An important benefit of Apache httpd is that you can modify the source as you require. While we do understand the desire to avoid re-applying patches to each new Apache httpd release, that ability allows users with unique requirements to tailor the Apache code to their own needs.