Contributing

PyDicer welcomes any and all contributions in the way of new functionality, bug fixes or documentation. This document provides some guidance to developers who would like to contribute to the project.

Git

Create a branch off of main while you make your changes or implement your new tool. Once complete, head to GitHub to create a pull request to merge your changes into the main branch. At this point the automated tests will run and maintainers will review your submission before merging.

Poetry

PyDicer uses poetry to manage dependencies. Instructions for installing poetry are available here. Once installed, you can easily install the libraries required to develop for PyDicer using the following command:

poetry install --with dev,docs --all-extras

This will automatically create a virtual environment managed by poetry. To run a script within this environment, use the poetry run followed by what to run. For example, to run a test.py script:

poetry run python test.py

Coding standards

Code in PyDicer must conform to Python’s PEP-8 standards to ensure consistent formatting between contributors. To ensure this, pylint is used to check code conforms to these standards before a Pull Request can be merged. You can run pylint from the command line using the following command:

pylint pydicer

But a better idea is to ensure you are using a Python IDE which supports linting (such as VSCode or PyCharm). Make sure you resolve all suggestions from pylint before submitting your pull request.

If you’re new to using pylint, you may like to read this guide.

Automated tests

A test suite is included in PyDicer which ensures that code contributed to the repository functions as expected and continues to function as further development takes place. Any code submitted via a pull request should include appropriate automated tests for the new code.

pytest is used as a testing library. Running the tests from the command line is really easy:

pytest

Add your tests to the appropriate file in the tests/ directory. See the pytest documention for more information.