Developer Guide

Warning

To create new processes look at examples in Emu.

Building the docs

First install dependencies for the documentation:

$ make develop

Run the Sphinx docs generator:

$ make docs

Running tests

Run tests using pytest.

First activate the finch Conda environment and install pytest.

$ source activate finch
$ pip install -r requirements_dev.txt  # if not already installed
# or
$ make develop

Run quick tests (skip slow and online):

$ pytest -m 'not slow and not online'"

Run all tests:

$ pytest

Check code formatting compliance:

$ pre-commit run --all-files

Run tests the lazy way

Do the same as above using the Makefile.

$ make test
$ make test-all
$ make lint

Updating the Conda environment

To update the conda specification file for building identical environments on a specific operating system:

Note

You should perform this regularly within your Pull Requests on your target OS and architecture (64-bit Linux).

$ conda env create -f environment.yml
$ source activate finch
$ make clean
$ make install
$ conda list -n finch --explicit > spec-file.txt

Preparing Finch releases

In order to prepare a new release version of Finch, perform the following steps in a new branch:

  1. Update CHANGES.rst with the release notes for the next version.

  2. Push changes to GitHub.

  3. Open a Pull Request with an appropriate title and description. (e.g. “Prepare release v1.2.3”)

  4. After merging changes to the main branch, click on the Actions tab and select the “Bump Version and Tag for Release” workflow.

  5. Adjust the information as needed (“Bump version”: “patch” or “minor” or “major”; “Tag”: “true” or “false”) the “Run Workflow” button on the main branch.

  6. After the workflow has completed, the new version will be tagged and pushed to GitHub.

  7. Create a new release on GitHub using the newly tagged commit with the same version number as the tag:

    • The release title should be the same as the tag name.

    • The release description should be the same as the release notes in CHANGES.rst.