Contributing to OptiMods¶

We welcome contributions from the community: bug fixes, doc corrections, extensions to existing Mods, or development of new Mods. This page describes conventions to follow when contributing, and the development process we follow for the project, which is applicable to all contributors. For guidelines on proposing and implementing new Mods, see Adding a new Mod.

Coding Standards¶

We use black to format all source code. pre-commit takes care of this formatting when installed (see Development Environment) and runs checks automatically when you commit changes. To run code quality checks manually, run the following and ensure no issues are reported:

pre-commit run --all-files
python -m flake8 . --select=E9,F63,F7,F82,F811,F401 --show-source

We follow the numpydoc style guide for docstrings of all public API functions.

Testing¶

All new additions, including bug fixes, Mod extensions, or brand new Mods must include unit tests to verify their functionality. We use unittest to test Mod functionality and sphinx doctest to ensure code snippets provided in the documentation work as expected.

Documentation¶

Documentation is a core part of the OptiMods project. All Mods must be accompanied by a documentation page explaining their use and providing appropriate background information. If new Mod features are added, the documentation must reflect the changes.

Development Environment¶

To set up your development environment:

Create and activate a Python virtual environment using your preferred tool. You can use any currently supported Python version for development (versions 3.8 through 3.12).
Run make develop from the top level of the repository. This command will install (using pip) all packages required to run the unit tests, run the doc tests, and build the sphinx documentation. It will also install pre-commit hooks to enforce coding standards.

To run the tests:

Activate your virtual environment.
Run make test. This command will run the unit tests of all Mod implementations, and the doctests for examples in the documentation.

To build and view the docs:

Activate your virtual environment and change to the docs directory.
Run make livehtml. This command will build the docs and open up a browser window at the index page.
Start editing the docs! Any changes to the documentation source files will automatically trigger a rebuild of the docs and a refresh of your browser window.

Developer Workflow¶

We use issues and pull requests to manage and review contributions.

Minor doc fixes can be submitted directly as pull requests.
Bugs should first be reported as issues before submitting a pull request to fix them. Use the ‘Bug report’ issue template.
New Mod proposals should first be submitted as issues for discussion; see Adding a new Mod for further details.