# Release Checklist

.. IMPORTANT::

   When building documentation for multiple versions of Zuar Runner (e.g.,
   `make versions`), the `sphinx-multiversion` command is used instead
   of `sphinx-build`.  For `sphinx-multiversion` to work properly, all
   documentation **must be checked-in** to the repository.
   Changes made locally, but not checked-in, will not appear in the
   generated documentation.

Steps to build and publish a new Zuar Runner release.

* Release number

  Some commands require knowledge of the current Zuar Runner release number
  that is being built. This must exactly match the tag for the
  release.

  Some examples on this page use `2.8.11` as an example of the current
  release number.

* Documentation

  * Setup documentation build environment
    ```
	cd docs
	make pyenv
	```

  * Ensure that all JSON schema documents are up-to-date and
    checked-in.
	```
	cd docs
	make schemas
	make PVT=y schemas
	```
	This will create JSON schema documentation in:
	```
	docs/src/schemas
	docs/srcp/schemas
	```

  * Update the release notes.
	```
	cd docs
	MITTO_REL=2.8.11 make release_notes
	```	
	This will create `docs/src/release_notes/2.8.11.md`.
	
	Manually update `docs/src/release_notes/index.md`.
	
  * Update `mitto/docs/conf.py`

    * Set `version` to the release's version number.

	* `release_tags__` contains all of the tags for which
      documentation will be built.  Add the release's version number to
      the list, if necessary.

	* Set `smv_branch_whitelist` to match any branches (not tags) for
      which documentation should be created. This documentation is
      built in addition to that for `release_tags__`.
	  Typically, this should just be set to `r'^master$'`.

  * Build the documentation.
    ```
	cd docs

	MITTO_REL=2.8.11 make versions
	MITTO_REL=2.8.11 make versions-index
	```
	Generated documentation is placed under `docs/build/html`.

  * View the local documentation.
    ```
	cd docs
	make serve
	```

  *	Ensure that any changes to documentation, `conf.py`, etc. are
	added to the Zuar Runner repo. 
	```
	git status
	git add/commit/push etc.
	```

	.. IMPORTANT::
	   The generated HTML is never checked-in to the repo;
	   only the source documents are controlled.

* Testing
  * Continuous integration
	* CI workflow ran without error
  * Local tests
    * Database credentials present in `~/.mitto_test`
	  * `bigquery.ini`
	  * `mongodb.ini`
	  * `snowflake.ini`
	  * `mariadb.ini`
	  * `redshift.ini`
	  * `sqlserver.ini`
    * Service credentials present in `~/.mitto_test`
	  * `job_rest_export.env`
	  * `job_subscriptions-admin.env`
	  * `job_subscriptions-non_admin.env`
	  * `job_tableau_export.ini`
	  * `job_vizql_export.env`
    * Test configurations present in `~/.mitto_test`
	  * `sampling.ini`
    * Run `make all` then `make test_all` locally.
      * Tests run without error


* Build
* Publish
* Jira