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     
  
  - Check out https://github.com/NeoGeographyToolkit/BinaryBuilder
    in your $HOME. 

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

  - 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.) The
    'forever' DOI on Zenodo is
    https://zenodo.org/badge/latestdoi/714891 which should resolve 
    to the 'latest' DOI.

  - Build the documentation in StereoPipeline/docs:

	make html
		tests building 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.
  
6.) Build and package the ASP release tarball. See:

        BinaryBuilder/README.

    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: The step above is 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 and that the documentation is searchable (this is a bug in
    some gs versions).

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.

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.
