High level release procedure that we follow to make a formal release for the
getdns API project.  This is a recipe - if you have a better way to do it then
update this document and share it with us.

- code freeze
    confirm with core team that all commits are in, from this point forward
    only bug fixes should be committed to the release branch, once the release
    is cut nothing should be committed to the release branch (make a new release)

- create a release branch
    in git repository named for the release, e.g. "release/v1.0.0-b3"
    we do this because folks may want to continue to work in the develop branch
    and be free to commit changes without injuring the release process.  Since
    building and testing binaries for a release takes a few days we don't want to
    force changes to queue up.

    One might argue that a release can be cut more quickly, however there are 
    inevitably little tweaks that need to be made that get uncovered as a result
    of the binary builds - these tweaks need to be included in the souces for
    this release so building the source tarball can't be done until all of the
    binaries have been built and tested.

- clone repo release branch to a clean local repo
    this should be a brand spanking new directory - don't try to shortcut it and
    use a working directory with lots of cruft - crap will find its way into the
    release and embarass you:

    # git clone -b v1.0.0-b3 https://github.com/getdnsapi/getdns.git getdns-1.0.0-b3

- update files to reflect release number/date
    ./README.md
    ./ChangeLog 
    ./configure.ac 
      - Watch for and change values:
        - AC_INIT
        - RELEASE_CANDIDATE
        - GETDNS_NUMERIC_VERSION
	- API_VERSION and API_NUMERUC_VERSION
	- read section "Library version" and
	  update GETDNS_LIBVERSION carefully!

    # autoreconf -fi

    commit these changes to the release branch

    # git commit -a -m "release number and date updates"
    # git push

- Do the unit tests on as many different systems as you can.  They must all
  be able to fulfill all requirements.  So they have libidn, libev, libuv, libevent,
  latest libunbound, latest openssl (at least 1.0.2) lastest clang compiler
  (for static analysis), latest valigrind.  Then run:

    # ${GETDNS_SRCDIR}/src/test/tpkg/run-all.sh

  and evaluate the results.

- build and sign source distribution tarball:
    # rm -fr *
    # git reset --hard
    # git submodule update --init
    # autoreconf -fi
    # libtoolize -ci
    # ./configure
    # make pub

    - test the resulting tar by building it and running the regression tests
      on as many different systems as you can.

- install on each target platform
    - make sure and use a user that was NOT used for the build, this will uncover 
      any silliness related to absolute paths in the build

- if a build breaks or an install fails then commit fixes to the relase branch
  - rebuild EVERY binary using the changed release branch

- merge branch changes back into master

- once all binaries are built and tested clean, create source tar ball

  you may need to run this as root to permit the chown
  # make clean
  # make pub
  generates getdns-1.0.0-b3.tar.gz + checksums + signatures

- upload source tarball and checsums and signatures to the getdnsapi.net site

  # scp getdns-1.0.0-b3.tar.gz* getdnsapi.net:/usr/local/www/apache24/data/dist

- Create and push signed tags to github

  # git -s v1.0.0-b3
  # git push --tags

- update getdnsapi.net web site 
    -  create a getdns-1.0.0-b3.tar.gz.changelog and
       getdns-1.0.0-b3.tar.gz.html in
        /usr/local/www/apache24/data/dist
       with the content of ChangeLog
       and the release announcement respectively.
    - Edit /usr/local/www/apache24/build_site.py.
      Change latest entry and create a new news_item entry.
    - rebuild website
        # cd /usr/local/www/apache24
        # ./build_site.py

- announce message to
    users@getdnsapi.net, spec@getdnsapi.net and maintainers@nlnetlabs.nl