Steps for Making a PDAL Release
==============================================================================

:Author: Howard Butler
:Contact: howard@hobu.co
:Date: 04/04/2018

This document describes the process for releasing a new version of PDAL.

General Notes
------------------------------------------------------------------------------

Release Process

1) Increment Version Numbers

  - CMakeLists.txt
    * project(PDAL VERSION 1.0.0 LANGUAGES CXX C)
    * CMake will break version down into PDAL_VERSION_MAJOR,
      PDAL_VERSION_MINOR, PDAL_VERSION_PATCH, and PDAL_VERSION_TWEAK.

  - Update SO versioning
    set(PDAL_API_VERSION "1")
    set(PDAL_BUILD_VERSION "1.0.0")
    * https://github.com/libspatialindex/libspatialindex/pull/44#issuecomment-57088783

  - doc/download.rst point to new release

  - Make and push new release branch

    ::

        git branch 2.0-maintenance
        git push origin 2.0-maintenance


  - Increment the doc build branch of .travis.yml:

    "$TRAVIS_BRANCH" = "2.0-maintenance"

  - Make DockerHub build entry for new release branch.


2) Write and update release notes. Use the PDAL "releases" section to create one.
   Write the document in Markdown for convenience on GitHub.

   - Manually store a copy of it in ./doc/development/release-notes/1.8.0.md
     for future reference.

   - Convert it to reStructuredText using pandoc and add the output to the
     RELEASENOTES.txt document

     ::

        pandoc --from markdown --to rst --output=1.8.rst doc/development/release-notes/1.8.0.md

3) Build and run the tests.  Really.

    ::

        ctest -V


4) Clone a new tree and issue cmake. The package_source CMake target is
   aggressive about scooping up every file in the tree to include in the package.
   It does ok with CMake-specific stuff, but any other cruft in the tree is
   likely to get dumped into the package.

   ::

        git clone git://github.com/PDAL/PDAL.git pdal2
        cmake .

5) Make the source distribution. If you are doing a release candidate
   add an RC tag to the invocation.

  ::

      ./package.sh
      ./package.sh RC1


   package.sh will rename the source files if necessary for the release
   candidate tag and create .md5 sum files. This script only works on
   linux and windows.

6) Update docs/download.txt to point at the location of the new release


7) Write the release notes. Email PDAL mailing list with notice about release

8) Update Alpine package

  - The PDAL Alpine package lives at
    https://github.com/alpinelinux/aports/blob/master/testing/pdal/APKBUILD.
    Pull requests can be made against the alpinelinux/aports repository. If the
    build configuration alone is changing, with no version increase, simply
    increment the build number `pkgrel`. If the `pkgver` is changing, then
    reset `pkgrel` to 0.
  - Pull requests should have a commit message of the following form
    `testing/pdal: <description>`.

9) Update Conda package

  - For PDAL releases that bump version number, but do not change dependencies
    or build configurations, the `regro-cf-autotick-bot` should automatically
    create a pull request at https://github.com/conda-forge/pdal-feedstock.
    Once the builds succeed, the PR can be merged and the updated package will
    soon be available in the `conda-forge` channel. If the PR does not build
    successfully, updates to the PR can be pushed to the bot's branch. Version
    bumps should reset the build number to zero.
  - Updates that alter the build configuration but do not bump the version
    number should be submitted as PRs from a fork of the
    https://github.com/conda-forge/pdal-feedstock repository. In these cases,
    the build number should be incremented.