RELEASEGUIDE

HOW TO MAKE A RELEASE

Here's a developer's checklist for performing a binary Ames Stereo
Pipeline (ASP) release.

1.) Modify the build system:

Inside both the ASP and VW src/CMakeLists.txt set the new
version. After the last release (x.y.0), the ASP version is likely
x.y.0-alpha, and so you just need to change it to x.y.0 if this is a
feature release.  If this is a bugfix release or a major release
instead, then set the version number of the release appropriately (see
https://semver.org for guidance).

2.) Update NEWS.rst.

3.) Commit all changes.

4.) Read and update the documentation.

5.) Build and package the software and documentation:

  - Fetch the latest ISIS using conda. 

  - Fetch the recipes for all ASP dependencies from:

   https://github.com/NeoGeographyToolkit

   (all of the repositories there ending with "feedstock"). Ensure
   that all versions there agree with the versions from the ISIS
   environment. Rebuild them with conda-build and commit them to:

      https://anaconda.org/nasa-ames-stereo-pipeline  

   This is described in detail in :numref:`conda_build` in the
   documentation.

  - Create a local conda environment and install there all the
    packages just built, including VisionWorkbench and StereoPipeline.
    This will ensure there are no conflicts. 

    The obtained current environment can be exported with the command:
  
      conda env export > asp.yml

   A copy of this file can be made, called ``asp_deps.yml``,
   with the VisionWorkbench and StereoPipeline packages removed from
   it, then edited to change the ``name`` field on top and removing
   the ``prefix`` field at the bottom. Then this file can be used to
   create an environment having only the ASP dependencies with the
   command:

     conda env create -f asp_deps.yml     
  
    Save a record of these in StereoPipeline/conda. It helps with future
    reproducibility.

  - Check out https://github.com/NeoGeographyToolkit/BinaryBuilder
    in your $HOME. 

  - ISIS expects a full Python distribution to be shipped. For now
    we handle this in an awkward way. A fresh conda environemnt
    is created having only Python and numpy, with versions
    as expected by ISIS, then that env is copied to BinaryBuilder as
    'python3.6'. This directory is packaged later with the build with
    make-dist.py.

  - Update the path to your local conda environment having the latest
    ASP dependencies in BinaryBuilder/auto_build/utils.sh.

  - Update this path as well in StereoPipelineTest, in the
    release*conf files, to be used for the nightly regressions.

  - Ensure your conda environment does not have VisionWorkbench and
    Stereo Pipeline include files, libraries, or executables, as those
    will conflict with building locally. 

  - Update the ISIS version in README.rst, INSTALLGUIDE.rst, and 
    conda_build.rst.
 
  - Update the ASP version and Zenodo link in README.rst. (The 
    release needs to be pushed to GitHub before the Zenodo link
    can be minted and hence that should be updated later.) 

    A custom tool needs to be created, based on the current
    daily release tool which will push a release with properly
    written metadata. If instead a daily release is renamed,
    the metatadata will be messed up (to be done). 

    Then visit https://zenodo.org/badge/latestdoi/714891 
    (which will always point to the 'latest' DOI) and find
    there that release's URL and put it in README.rst. 

6.) Build and package the ASP release tarball. See:

        BinaryBuilder/README.

  - Build the documentation in StereoPipeline/docs. See
    https://stereopipeline.readthedocs.io/en/latest/installation.html#building-the-documentation
    for how to fetch sphinx. Run:

	make html
		builds a local copy of the online documentation

	make latexpdf
		builds 'the pdf book'

  - Copy the pdf book from docs/_build/latex/asp_book.pdf to
    $HOME/BinaryBuilder/dist-add/asp_book.pdf.
  
    Ideally all the dependencies are already built and installed
    with conda as above. VisionWorkbench can be built and installed
    either with conda or with BinaryBuilder.

    Use the compilers provided by conda (on Linux).
 
    Test all binary releases on different machines by running
    StereoPipelineTest.

    NOTE: All items in this step are done automatically by running on
    lunokhod1 the script

      $HOME/projects/BinaryBuilder/auto_build/launch_master.sh

The resulting release tarballs will go to BinaryBuilder/asp_tarballs.

7.) Check that the ASP version is correct in the documentation
    file.

8.) Commit and tag the release in the VW and ASP repos. Example: 

  git tag 3.1.0

Push the tags to the remote server with: 

 git push origin 3.1.0 # commit to your branch
 git push god    3.1.0 # commit to main branch

(Here it is assumed that 'origin' points to your own fork and 'god'
points to the parent repository.)

If more commits were made and it is desired to apply this tag to a
different commit, first remove the exiting tag with:

  git tag -d 3.1.0
  git push origin :refs/tags/3.1.0
  git push god    :refs/tags/3.1.0

9.) Upload the builds and the pdf documentation to GitHub, in the
release area. Or just rename the latest uploaded daily build
to be the release build. 

Add the changes listed in NEWS.txt to the release area.

Update the website, at::

  https://ti.arc.nasa.gov/cms/pages/page/ 

(SG can give permissions to edit the pages under
/tech/asr/intelligent-robotics/ngt). 

Update:
 - The sidebar 
 - The main page, including:
   * Binary release links
   * ISIS version
   * Source code release link
   * Documentation link

10.) Ask fellow ASP developers to do some tests and review the
documentation.

11.) Send an announcement of the new release to the mailing list, at
https://groups.google.com/forum/\#!forum/ames-stereo-pipeline-support
and the old stereo-pipeline@lists.nasa.gov, listing the changes
specified in NEWS.rst.

12.) Modify the build system.

After the release has been done, prep the repo for the next phase of
development, by updating the version number in:

 - src/CMakeLists.txt

in both the VW and ASP repositories. 

If you just released version 3.1.0, we expect that the next feature
release will be 3.2.0, if a major release, or 3.1.1 if a minor
release, so the version tag should be updated to 3.2.0-alpha in
anticipation (see https://semver.org for guidance).

13.) Reflect any changes in release policy by modifying this document.

14.) Commit changes.