Skip to content

Latest commit

 

History

History
77 lines (52 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

77 lines (52 loc) · 3.25 KB
Raw

PyFlyt Contribution Guidelines

At this time we are currently accepting the current forms of contributions:

  • Bug reports
  • Pull requests for bug fixes
  • Documentation improvements
  • Features

We may accept these contributions as well, but the approval process may take some time as we try to keep implementations here as high quality as possible:

  • New vehicles
  • New environments
  • New components

Development

This section contains technical instructions & hints for the contributors.

Code Formatting and Tests

TLDR;

  1. Download the dev dependencies with pip3 install -e .[dev].
  2. Run pre-commit with pre-commit run --all-files.
  3. Run the test suite pytest tests.

Type checking

The project uses pyright to check types. To type check locally, install pyright per official instructions. It's configuration lives within pyproject.toml. It includes list of included and excluded files currently supporting type checks. To run pyright for the project, run the pre-commit process (pre-commit run --all-files) or pyright --project=pyproject.toml Alternatively, pyright is a built-in feature of VSCode that will automatically provide type hinting.

Docstrings

Pydocstyle has been added to the pre-commit process such that all new functions follow the google docstring style. All new functions require either a short docstring, a single line explaining the purpose of a function or a multiline docstring that documents each argument and the return type (if there is one) of the function. In addition, new file and class require top docstrings that should outline the purpose of the file/class. For classes, code block examples can be provided in the top docstring and not the constructor arguments.

To check your docstrings are correct, run pre-commit run --all-files or pydocstyle --source --explain --convention=google. If any docstrings fail, the source and reason for the failure is provided.

Git hooks

The CI will run several checks on the new code pushed to the repository. These checks can also be run locally without waiting for the CI by following the steps below:

  1. install pre-commit,
  2. Install the Git hooks by running pre-commit install.

Once those two steps are done, the Git hooks will be run automatically at every new commit. The Git hooks can also be run manually with pre-commit run --all-files, and if needed they can be skipped (not recommended) with git commit --no-verify. Note: you may have to run pre-commit run --all-files manually a couple of times to make it pass when you commit, as each formatting tool will first format the code and fail the first time but should pass the second time.

Additionally, for pull requests, the project runs a number of tests for the whole project using pytest. These tests can be run locally with pytest in the root folder.

Building the docs

Make sure that you have install the requirements:

cd docs_source
pip install -r requirements.txt

Then run

./build_docs.sh

Now, navigate to docs and open index.html in your browser.