                           Maintaining WebAuth

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

Terminology

  Please use the following terms consistently throughout the WebAuth
  source code and documentation:

  attribute
      A single key-value pair in the WebAuth token format, normally
      directly corresponding to a struct member in the webauth_token
      struct representation.

  code
      An error code from something *other* than WebAuth, usually either
      APR or Kerberos.  Use code instead of status for these to
      distinguish from a WebAuth status code.  If both Kerberos and APR
      are in use in the same function, use code for the Kerberos status
      code and acode for the APR status code.

  raw token
      An encrypted token that has not been base64-encoded.  These are used
      in only a small number of places, primarily when one type of token
      with one encryption key is contained in another token with a
      different encryption key.

  status
      A WebAuth status code; specifically, one of the members of the
      webauth_status enum.  Try to avoid using status for things other
      than WebAuth status codes, since mixing and matching codes from
      different subsystems gets confusing.

  token
      A WebAuth protocol token.  This comes in three forms: a
      webauth_token struct (representing any token), one of the specific
      webauth_token_* structs for a particular token, or an encrypted and
      base64-encoded string.

Standard Namespace Prefixes

  All macros, functions, struct names, union names, and enum names used in
  WebAuth code should have standard prefixes to maintain namespace
  separation from other C libraries and user code.  The following prefixes
  are used for all types of public names except macros:

  mwa_          Internal to mod_webauth
  mwk_          Internal to mod_webkdc
  mwl_          Internal to mod_webauthldap
  wai_          Internal to libwebauth and not visible outside it
  wat_          Internal to the WebAuth test suite
  webauth_      Part of the public WebAuth API

  For macros, use the following:

  MWA_          Internal to mod_webauth
  MWK_          Internal to mod_webkdc
  WA_           Part of the public WebAuth API or internal to libwebauth

Standard Variable Names

  Use the following variables by preference in all WebAuth code for
  consistency.  It makes it much easier to read unfamiliar parts of the
  code.

  ctx
      The WebAuth context.

  kc
      The WebAuth Kerberos context (struct webauth_krb5 *).

  s
      The WebAuth status code.  Used either for storing the results of
      running WebAuth functions that return a status code or for storing
      the status code that will be returned by this function (or
      frequently both).

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.4.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/webauth/doc/mod_*.xml* ../mod/
      ./build.sh

  Following that procedure 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.

  After copying the files back, run docs/scripts/clean-apache-manual on
  each of the newly-generated HTML files.  This script will clean up some
  problems with the HTML generated by the Apache build process, generally
  by removing parts that are specific to the internal Apache
  documentation.

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 whether the shared library revision needs to be increased.
      This is set in Makefile.am in the LDFLAGS setting for libwebauth.la.
      Follow the instructions in the "Updating version info" section of
      the Libtool manual.

      If backward-incompatible changes were made to the library ABI, also
      change the symbol versioning in lib/libwebauth.map by changing the
      numbers after WEBAUTH to match the new major release of the WebAuth
      package.  (Any backward-incompatible changes should generally force
      an increase of the second version number of the WebAuth version.)

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

   4. Run make distcheck.  This will generate .tar.gz and .tar.xz files
      containing the source distribution and run through the test suite.

   5. 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 "WebAuth release <version>".

   6. Prepare new Debian packages.  Switch to the Debian branch and import
      the new upstream tarball with the command:

        $ gbp import-orig --upstream-vcs-tag release/<version> <path>

      where <path> is the path to the .tar.xz file.  (If you have
      previously done this for the same version and are reimporting,
      delete the upstream/<version> tag first with git tag -d.)  For older
      versions of git-buildpackage, use git-import-orig as the command
      instead.  Then update the packaging as needed, including a new
      changelog entry, and build the package and ensure it passes its test
      suite.

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

   8. Sign the .tar.gz and .tar.xz files with the WebAuth signing key:

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

      where <dist>.tar.gz is the distribution tarball.

   9. Copy the resulting .tar.gz, .tar.gz.asc, .tar.xz, and .tar.xz.asc
      files into the dist subdirectory of the WebAuth web site.

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

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

  12. Post the release announcement to the appropriate mailing lists.

License

  Copyright 2009, 2010, 2011, 2012, 2013, 2014
    The Board of Trustees of the Leland Stanford Junior University

  Copying and distribution of this file, with or without modification, are
  permitted in any medium without royalty provided the copyright notice
  and this notice are preserved.  This file is offered as-is, without any
  warranty.
