
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
    * set(PDAL_VERSION_STRING "1.0.0" CACHE STRING "PDAL version")
    * DISSECT_VERSION() CMake macro will break version down into
      PDAL_VERSION_MAJOR, PDAL_VERSION_MINOR, PDAL_VERSION_PATCH,
      and PDAL_CANDIDATE_VERSION strings.

  - 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/quickstart.rst has a number of current-release references

  - doc/download.rst point to new release

  - Make and push new release branch

    ::

        git branch 1.7-maintenance
        git push origin 1.7-maintenance


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

    "$TRAVIS_BRANCH" = "1.7-maintenance"

  - Make DockerHub build entry for new release branch.


2) Update README to include any relevant info about the release that
   might have changed.

3) Update ChangeLog with git2cl

  * git2cl . > ChangeLog

4) Build and run the tests.  Really.

    ::

        ctest -V


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

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

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

8) Upload the new release to download.osgeo.org:/osgeo/download/pdal

  ::

        scp PDAL-* hobu@download.osgeo.org:/osgeo/download/pdal

9) Tag the release.  Use the ``-f`` switch if you are retagging because you
   missed something.

  ::
        git tag 1.0.0
        git push --tags


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


11) Upload new OSGeo4W package to download.osgeo.org:/osgeo/download/osgeo4w/x86_64/release/pdal

  - Go to https://ci.appveyor.com/project/hobu/pdal
  - Choose ``OSGEO4W_BUILD=ON`` build
  - Scroll to very bottom
  - Fetch tarball "OSGeo4W64 build will be uploaded to https://s3.amazonaws.com/pdal/osgeo4w/pdal-a4af2420b09725a4a0fff1ef277b1.7370c497d2.tar.bz2"

  - rename to match current release and set OSGeo4W build number to 1

    ::

        mv pdal-a4af2420b09725a4a0fff1ef277b1.7370c497d2.tar.bz2 pdal-1.7.0-1.tar.bz2

  - copy to OSGeo4W server

    ::

        scp pdal-1.7.0-1.tar.bz2 hobu@download.osgeo.org:/osgeo/download/osgeo4w/x86_64/release/pdal

  - refresh OSGeo4W

    ::
        http://upload.osgeo.org/cgi-bin/osgeo4w-regen.sh


  - promote release

    ::

        http://upload.osgeo.org/cgi-bin/osgeo4w-promote.sh
