Development#

This is a summary of code conventions used in maize.

Installation#

If you will be working on both maize and maize-contrib it will be easiest to install the environment for maize-contrib first, as it encompasses all dependencies for maize and domain-specific extensions. You can then install both packages using editable installs.

Code style#

We use the PEP 8 convention with a 100 character line length - you can use black as a formatter with the --line-length=100 argument. The code base features full static typing, use the following mypy command to check it:

mypy --follow-imports=silent --ignore-missing-imports --strict maize

Type hints should only be omitted when either mypy or typing doesn’t yet fully support the required feature, such as higher-kinded types or type-tuples (PEP 646).

Caution

If you installed maize in editable mode you may need to specify its location with MYPYPATH to ensure mypy can find it. See this setuptools issue.

Documentation#

Every public class or function should feature a full docstring with a full description of parameters / attributes. We follow the numpy docstring standard for readability reasons. Docs are built using sphinx in the docs folder:

make html

There will be some warnings from autosummary that can be ignored. The built docs can then be found in docs/_build/html. To preview them locally you can start a local webserver running the following command in the docs/_build/html folder:

python -m http.server 8000

The docs are then available at http://localhost:8000/index.html.

If you add a new feature, you should mention the new behaviour in the User guide, in the Cookbook, and ideally add an example under Examples. If the feature necessitated a deeper change to the fundamental design, you should also update Design.

Testing#

Tests are written using pytest and cover the lower-level components as well as higher-level graph execution, and can be run with:

pytest --log-cli-level=DEBUG tests/

Any new features or custom nodes should be covered by suitable tests. To make testing the latter a bit easier, you can use the TestRig class together with MockChannel if required.

Coverage can be reported using:

pytest tests/ -v --cov maize --cov-report html:coverage

New versions#

To release a new version of maize, perform the following steps:

  1. Create a new branch titled release-x.x.x

  2. Add your changes to CHANGELOG.md

  3. Increment maize.__version__

  4. Commit your changes

  5. Rebuild and update the remote documentation (see above)

  6. Create a tag using git tag vx.x.x

  7. Push your changes with git push and git push --tags

  8. Update master:

    1. git checkout master

    2. git pull origin master

    3. git merge release-x.x.x

    4. git push origin master