Skip to content

Latest commit

 

History

History
73 lines (55 loc) · 3.37 KB

CONTRIBUTING.md

File metadata and controls

73 lines (55 loc) · 3.37 KB
Raw

Contributing

This is a summary of code conventions and contributing guidelines for maize-contrib.

Issues & Pull requests

To report bugs or suggest new features, open an issue, or submit a pull request with your changes.

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 PEP8 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 (PEP646).

Important

If you installed the maize core 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. Custom nodes should follow the example node in maize/steps/mai/example/step.py, default values will be detected and added to the documentation automatically. 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.

Testing

Tests are written using pytest, located together with the node, and can be run with:

pytest --log-cli-level=DEBUG maize/steps/mai/example/step.py

Any custom nodes should be covered by suitable tests in a TestSuite<node-name> class. To make testing the nodes a bit easier, you can use the maize.utilities.testing.TestRig class together with maize.utilities.testing.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 version in pyproject.toml
  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