Contributing#
Thank you for considering contributing to pymavswarm
! Here we provide a set of
guidelines for contributing to the project.
Contributions include but are not restricted to:
Contributing to the
pymavswarm
codebaseWriting documentation
Writing tests
Performing field tests
Reporting bugs
Answering discussion questions
Workflow#
Send all pull requests to the
main
branch (unless otherwise requested).Limit each pull request to resolving a single issue
It is your responsibility to ensure that your development branch is up-to-date with the
main
branch. You may either rebase onmain
or mergemain
into your development branch.Always test and document your code. We also encourage performing field tests for significant changes.
Ensure that your changes pass our CI. We will not review your PR until the CI passes.
Setting up a local development environment#
pymavswarm
provides two ways to configure a local development environment:
Using our VSCode development container
Using Pipenv
A VSCode development container has been provided to offer a fully sandboxed
development environment. This environment includes all development Python
packages (e.g., pre-commit
) used by the pymavswarm
development team and
utilizes a variety of VSCode extensions that make it easy to run tests and to
ensure that all style conventions are followed. Follow the instructions here to
learn how to install and launch development containers using VSCode. Once these steps
have been completed, launch the pymavswarm
project using the provided development
image. Launching the development image will also install pymavswarm
in
editable mode.
A Pipfile
has also been provided to enable support for creating and managing
a virtual environment using Pipenv. To use a virtual environment,
first ensure that pipenv
has been installed. After successfully installing
pipenv
, navigate to the base pymavswarm/
directory:
$ cd path/to/pymavswarm
Next, install the project dependencies:
$ pipenv install --dev
We also recommend installing pymavswarm
in editable mode:
$ pip3 install -e .
Finally, launch the virtual environment:
$ pipenv shell
At this point, running the project tests should work and pass (in both the development container and the virtual environment):
$ python3 -m unittest
Coding guidelines#
The following section documents the pymavswarm
coding guidelines (e.g.,
styling, convention, etc.)
Linting#
pymavswarm
uses pre-commit
to run code formatting checks such as black
,
flake8
, pydocstyle
, and isort
. If you have installed the project
using one of our recommended local development configurations, you may run
pre-commit
using the following command:
$ pre-commit run --all-files
We strongly recommend running pre-commit
before committing your code to
ensure that your commit follows our code style conventions. Any warnings from
these checks will cause the CI to fail.
Type hints#
pymavswarm
uses PEP 484 type-hints. Any new development should use type hints.
When using type-hints, it is preferred that built-in types are used (see PEP 585).
The Optional
type-hint should be avoided in favor of | None
. For example,
rather than
from typing import Optional
agent_location: Optional[Position] = None
You should use
from __future__ import annotations
agent_location = Position | None = None
Commonly used types will appear in pymavswarm.types
. These should be used
where applicable.
Writing documentation#
pymavswarm
uses Sphinx to generate online developer documentation from
docstrings. Broadly, docstrings should adhere to PEP 257, unless otherwise specified.
All docstrings should use triple quotation marks. Multi-line docstrings should
start on new-lines. Parameters and their types should be prefaced with :param
and :type
, respectively. All methods should have a short summary. An extended
summary should be used when an in-depth explanation of a method is required.
The following example demonstrates the Sphinx markdown conventions used by
pymavswarm
:
def compute_location(
current_location: Position | None = None
) -> Position | None:
"""
Demonstrate how to write a docstring.
Docstrings are a great way to add developer documentation.
:param current_location: current location of an agent, defaults to None
:type current_location: Position | None, optional
:return: computed agent location
:rtype: Position | None
"""
return current_location
Testing#
Unit tests should be implemented using unittest
. Unit tests should be
implemented whenever possible. Functional tests should be named def test_*
.
It is suggested that field tests are also performed when adding a code
contribution; however, this is not required (we understand that not everyone
has a fleet of drones laying around).
Support#
If you have questions regarding your contribution, please create a new
discussion post on the pymavswarm
Discussions board.