Contributing to Automata

November 3, 2025 ยท View on GitHub

Code of Conduct

When interacting with other users and maintainers, please be sure to abide by the Code of Conduct.

Submitting an issue

Bug reports

If you are submitting a bug report, please answer the following questions:

  1. What version of Automata were you using?
  2. What were you doing?
  3. What did you expect to happen?
  4. What happened instead?

Please provide any code to reproduce the issue, if possible.

New features

If you are requesting a new feature or change or behavior, please describe what you are looking for, and what value it will add to your use case.

Modifying the codebase

Automata is an open-source project under the MIT License, so you are welcome and encouraged to modify the codebase with new fixes and enhancements. Please observe the following guidelines when submitting pull requests for new fixes or features:

  1. All new code must comply with the enabled ruff lint rules. If you install Automata dependencies with uv, the ruff package should be available to you for this purpose with the config in pyproject.toml. The included VSCode configuration is set to run this formatting on save.

In addition, new code must include type annotations and pass typechecking run with mypy.

  1. Whether you are introducing a bug fix or a new feature, you must add tests to verify that your code additions function correctly and break nothing else.

  2. Please run uv run pytest --cov and ensure that your changes are covered.

  3. If you are adding a new feature or changing behavior, please update the documentation appropriately with the relevant information. This includes updating docstrings for all functions in the public interface, using the NumPy style. To run the documentation site locally, install the documentation dependencies with:

uv sync --group docs

Then, start the local server with the following command:

uv run mkdocs serve

Setting up your environment

The dependencies for the project are best managed with uv. For instructions on how to install uv, see the uv documentation.

To create a virtual environment and install all project dependencies (including dev dependencies), run:

uv sync --all-groups

Troubleshooting pygraphviz

If you run into any trouble building the wheel for pygraphviz on macOS when installing dependencies, try running:

brew install graphviz
# Proceed to install and build dependencies
uv sync --all-groups

Running unit tests

The project's unit tests are written using unittest and run using the pytest Python package. You can run all unit tests via the following command:

uv run pytest

Code coverage

The project currently boasts high code coverage across all source files. New contributions are expected to maintain this high standard. You can view the current coverage report via the following commands:

pytest --cov

If the coverage ever decreases, you can generate and open a detailed HTML view of the coverage report like so:

uv run coverage html
open htmlcov/index.html