ReleaseHowTo

Notes on how to Release

Note, this assumes one starts on master branch and is releasing a new major branch, X.Y.

1. Add and commit new versions file on master:

   • move input converters around: git mv tools/input_converters/xml-X.{Y-1}-X.Y.py

   • edit docs/documentation/source/_static/versions.json

     • change the version of the "stable" branch

     • add a new entry, after stable, to provide the previously-stable version:

         {
             "version": "X.(Y-1)",
             "url": "https://amanzi.github.io/ats/vX.(Y-1)/"
         }
       

   • edit docs/documentation/source/conf.py to change the default release number:

     • "html_theme_options"/"switcher"/"version_match" --> vX.Y
     • "release" --> vX.Y

   • git add docs/documentation/source/_static/versions.json docs/documentation/source/conf.py

   • git commit -m 'update versions'; git push

2. Clear out old, stable documentation:

   • cd docs/documentation/deploy/html
   • git mv stable vX.(Y-1)

3. Rebuild documentation:

   • cd ../../
   • Build the rst for input_spec: make input_spec
   • Build html: make html
   • Look for error messages, missing template parameters, etc, in the output.
   • Check to make sure things look ok: open build/html/index.html. If not, edit source and repeat.

4. Deploy the updated dev version:

   • make deploy_master

5. Cut a branch on each of ATS, ats-demos, and ats-regression-tests, e.g.:

   • git tag ats-demos-X.(Y+1)-dev
   • git push --tags
   • git checkout -b ats-demos-X.Y
   • git push --set-upstream origin ats-demos-X.Y

6. Update the ATS CI to run against the corresponding Amanzi branch

   • edit $ATS_SRC_DIR/.github/workflows/ats-ci.yml, changing jobs/build/steps/"name: Check out the Amanzi repo"/with/ref: master --> amanzi-X.Y

7. Deploy the stable documentation on the newly created ATS branch:

   • edit docs/documentation/source/conf.py to change version="dev" --> "X.Y". (NOT vX.Y)
   • make html
   • make deploy_stable

8. Commit the above changes to the version branch

   • git add source/conf.py ../../.github/workflow/ats-ci.yml
   • git commit -m 'reconfiguring documentation for release branch'
   • git push

9. Go to github Releases and “draft a new release”

   • Tag = ats-X.Y.0
   • @target branch = ats-X.Y
   • release name = ATS Release X.Y.0