                           Maintaining WebAuth

  This file contains procedures and information for WebAuth maintainers
  and for anyone else who is interested in modifying the WebAuth source.

Building Module Documentation

  The files doc/mod_*.xml have the module documentation for the Apache
  modules that come with WebAuth, in the XML format that is used for the
  Apache reference manual.  Pre-built copies of the HTML files suitable
  for dropping into a built Apache 2.x manual directory are also provided
  for convenience.

  Whenever the module documentation is changed in the XML files, the HTML
  files need to be rebuilt.  Basic instructions for doing so are at:

      <http://httpd.apache.org/docs-project/docsformat.html>

  The basic steps are as follows:

      svn co \
          http://svn.apache.org/repos/asf/httpd/httpd/branches/2.0.x/docs/ \
          apache-docs
      cd apache-docs/manual
      svn co http://svn.apache.org/repos/asf/httpd/docs-build/trunk build
      cd build
      JAVA_HOME=/usr/lib/jvm/default-java  # (whatever your java home is)
      export JAVA_HOME
      cp /path/to/webauth3/doc/mod_*.xml* ../mod/
      ./build.sh

  Following that procedure (assuming Java doesn't "run out of memory",
  which occasionally happens to me) should generate:

      ../mod/mod_web{auth,authldap,kdc}.html.en

  which can then be copied into the WebAuth tree.

  Once this infrastructure is set up, regenerating the documentation is
  only a matter of copying in new *.xml files and ./build.sh will
  incrementally rebuild only those files.

Making a Release

  Follow the following steps to make a new full release of WebAuth:

   1. Make sure that NEWS is up-to-date.  Update the release date in NEWS
      to the current date.  Update the revision number in configure.ac and
      in README to the new release.  Commit that change with a comment of
      "Release <version>".

   2. Check out a copy of the WebAuth tree, run ./autogen (making sure to
      use Autoconf 2.64, Automake 1.11, and Libtool 2.x or later
      versions), and run ./configure with whatever options are needed to
      get it to finish.

   3. Run make distcheck.  This will generate a .tar.gz file containing
      the source distribution and run through the test suite.

   4. Optionally, install this release on one server and run through the
      full test suite.  This may have already been done as part of the
      preparation for the release.  If one needs to wait for a bit before
      releasing at this point, don't forget to go back and update the date
      in NEWS and re-run make dist to generate the final tarballs when the
      release is actually ready.

   5. Sign the .tar.gz file with the WebAuth signing key:

        $ gpg --detach-sign --armor -u webauth-team@lists <dist>.tar.gz

      where <dist>.tar.gz is the distribution tarball.  Contact Russ about
      the signing key if you need to do this part and don't already have
      it.

   6. Copy the resulting .tar.gz and .tar.gz.asc files into the dist
      subdirectory of the WebAuth web site.  Also generate a file named
      <dist>.tar.gz.md5 containing the MD5 checksum of the *.tar.gz file
      and put that in the dist subdirectory.

   7. Based on the NEWS file, write up a release announcement.  Convert
      that announcement to thread and put it in the news subdirectory of
      the WebAuth web site.  The naming convention for release
      announcements is <version>-announce.th where <version> is the
      version of the release without any periods.  See the existing
      announcements for the structure and the correct sidebar links.

      Add a short news entry to the main page and also to the index.th
      file in the news directory.

   8. Update the MD5 checksum and the links in download.th to correspond
      to the current release.

   9. Post the release announcement to the appropriate newsgroups and
      mailing lists.

  10. Going back to the checked-out tree that you used to generate the
      release, tag the release point with git tag -s release/<version> and
      a tag comment of "Release <version>".
