
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

  - appveyor.yml

  - 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) 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.7.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.7.rst doc/development/release-notes/1.7.0.md

3) Update ChangeLog with git2cl

  * git2cl . > ChangeLog
  * Delete any lines with "Merge" in them

    ::

         git2cl . > Changelog
         gsed -i '/Merge/d' ./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
