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

:Author: Howard Butler
:Contact: howard@hobu.co
:Date: 05/31/2017

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.

  - python/VERSION.txt
    python/pdal/__init.py

  - 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

  - Make and push new release branch

    ::

        git branch 1.6-maintenance
        git push origin 1.6-maintenance


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

    "$TRAVIS_BRANCH" = "1.6-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 Python extension to PyPI

  ::

      cd python; python setup.py sdist upload

12) 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-a4af2420b09725a4a0fff1ef277b1e6370c497d2.tar.bz2"

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

    ::

        mv pdal-a4af2420b09725a4a0fff1ef277b1e6370c497d2.tar.bz2 pdal-1.6.0-1.tar.bz2

  - copy to OSGeo4W server

    ::

        scp pdal-1.6.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


13) Publish JNI Bindings
    What you need:
        - an account on sonatype (https://issues.sonatype.org/secure/Signup!default.jspa)
        - ~/.sbt/1.0/sonatype.sbt file with the following content:
            credentials += Credentials("Sonatype Nexus Repository Manager",
                           "oss.sonatype.org",
                           "<your username>",
                           "<your password>")

    The description of the Sonatype publishment process (everything described below is in a java dir: cd PDAL/java):
        - Publishing snaphots:
            Snapshot can be published without PGP sign, it is published to a snapshot repo and allows immediate snaphot updates.
            To publish everything in a local repo use command:
              - ./scripts/publish-local.sh (publishes scala 2.11 version)
              - ./scripts/publish-local-212.sh (publishes scala 2.12 version)
            To publish everything into sonatype snapshot repo use:
              - ./scripts/publish-all.sh
            Summary:
              - Run ./scripts/publish-all.sh and everything is available in a snaphost repository
        - Publishing releases:
            To publish everything into sonatype snapshot repo (staging repo) use:
              - ./scripts/publish-all.sh --suffix="" --signed
               `suffix` defines version suffix (for example `--suffix="-RC1"`)
               `signed` means that jar would be uploaded into a staging sonatype repo with a PGP sign
            Staging means a special repository in a pre released condition.
              - Go into staging repos panel: https://oss.sonatype.org/#stagingRepositories (log in using sonatype user / pwd)
              - Filter by package name (pdal in our case) and select staging repo
              - Press Close button on the top of the table with repos. It would run packages
                validation and will close staging repo in a succesfull case
              - After succesfull closing press Release button. It would be immediately published into sonatype releases repo,
                and synced with maven central ~ in 10 minutes and ~ in 2 hours it would be indexed here:
                http://search.maven.org/#search%7Cga%7C1%7Cio.pdal
            Full official guide: http://central.sonatype.org/pages/ossrh-guide.html
            Deploying to sonatype using sbt official doc: http://www.scala-sbt.org/release/docs/Using-Sonatype.html
            Official sonatype guide with pics of (https://oss.sonatype.org/#stagingRepositories) and answers the question what
            to do after jars were published into a staging repo (in our case after ./scripts/publish-all.sh --suffix="" --signed step)
            Summary:
              - Run ./scripts/publish-all.sh --suffix="" --signed to publish everything into staging repo
              - Go to sonatype panel https://oss.sonatype.org/#stagingRepositories and release the jar
              - Await ~10 minutes to have jars published to maven central
