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.

  - Make the conda dependencies of:

      https://github.com/NeoGeographyToolkit/MultiView
    
    compatible with the dependencies so far, then build and install
    that package in the same directory as VisionWorkbench and
    StereoPipeline.

  - 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, numpy, with versions
    as expected by current ISIS, for example, as:

      conda create -n python_isis7 -y python=3.9.15 numpy=1.23.5

    This directory is packaged later with the build with make-dist.py
    (that tool needs to be edited to ensure the path to this
    environemnt is used). See also BinaryBuilder/README.

  - 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 
    building_asp.rst (there can be many mentions in each).
 
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.2.0

Push the tags to the remote server with: 

 git push origin 3.2.0 # commit to your branch
 git push god    3.2.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.2.0
  git push origin :refs/tags/3.2.0
  git push god    :refs/tags/3.2.0

9.) Create a new release on GitHub, and upload to it the builds and
the pdf documentation. Use the just-created tag.  Do not just rename
the latest uploaded daily build, as that will create an incorrect
Zenodo link. Paste in the release area the current release notes from
NEWS.txt.

Files can be uploaded to a release from the browser, or from the
command line, with the GitHub "gh" tool. Here's an example usage:

  cd BinaryBuilder
  for file in asp_tarballs/StereoPipeline-3.2.0-2023-01-01-x86_64-Linux.tar.bz2 \
              asp_tarballs/StereoPipeline-3.2.0-2023-01-01-x86_64-OSX.tar.bz2   \
              dist-add/asp_book.pdf; \
  do 
    gh release upload 3.2.0 $file \
      -R git@github.com:NeoGeographyToolkit/StereoPipeline.git   
  done

Wait a few minutes for Zenodo to mint a link, then visit the Zenodo
page at https://zenodo.org/badge/latestdoi/714891 (which will always
point to the 'latest' DOI) and find there this release's URL and put
it at the top of README.rst, in the appropriate ``target`` field.
Increment the version in the ``image`` field right above that.
Push this update.

Get the text on the GitHub release page right the first time, as once
Zenodo picks it up, the Zenodo page cannot be modified. But the binaries
attached to the release can be modified or added later.

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

11.) 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 version 3.2.0 just got released, we expect that the next feature
release will be 3.3.0, if a major release, or 3.2.1 if a minor
release, so the version tag should be updated to 3.2.1-alpha in
anticipation (see https://semver.org for guidance).

12.) Update this document as it becomes necessary.
