Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (60 loc) · 4.46 KB

CONTRIBUTING.md

File metadata and controls

98 lines (60 loc) · 4.46 KB

Contributing

General guidelines

If you haven't contributed to open-source before, we recommend you read this excellent guide by GitHub on how to contribute to open source. The guide is long, so you can gloss over things you're familiar with.

If you're not already familiar with it, we follow the fork and pull model on GitHub. Also, check out this recommended git workflow.

Contributing Code

This project has a number of requirements for all code contributed.

  • We follow the PEP-8 style convention.
  • We use NumPy-style docstrings.
  • It's ideal if user-facing API changes or new features have documentation added.
  • It is best if all new functionality and/or bug fixes have unit tests added with each use-case.

Setting up Your Development Environment

This project uses the uv project manager and uv_build build backend.

To set up your dev environment, run:

uv sync

This command will include the requirements from the dev dependency group by default, which includes dependencies for development, testing, and documentation.

Alternatively, if you prefer to manage your virtual environments yourself, you can install the package for development using, for example:

python -m venv .venv
source .venv/bin/activate
pip install --group dev -e .

For all pull requests, linting and unit tests are automatically run using the GitHub Actions Continuous Integration service. However, you are still encouraged to run these checks locally before pushing code to a PR.

Linting and Formatting

We use ruff for style checking.

uv run ruff check

Ruff can fix a lot of errors itself.

uv run ruff check --fix

Ruff includes a formatter that mimics black. To automatically reformat your code, you can use ruff format {source_file}.

We use pre-commit to make sure the coding style is enforced. You first need to install pre-commit and the corresponding git commit hooks:

uv run pre-commit install

The last command installs the hooks listed in .pre-commit-config.yaml locally into your git repo. If you do this, the checks will run automatically before every commit. You can also manually make sure your code satisfies the coding style:

uv run pre-commit run --all-files

Testing

It is best if all new functionality and/or bug fixes have unit tests added with each use-case.

We use pytest as our unit testing framework. Once you've configured your environment, you can just cd to the root of your repository and run:

uv run pytest

Documentation

If a feature is stable and relatively finalized, it is time to add it to the documentation. If you are adding any private/public functions, it is best to add docstrings, to aid in reviewing code and also for the API reference.

We use Numpy style docstrings and Sphinx to document this library. Sphinx, in turn, uses reStructuredText as its markup language for adding code.

We use the Sphinx Autosummary extension to generate API references. You may want to look at docs/api-*.rst files to see how they look and where to add new functions, classes or modules. We also use the myst_nb extension to render Jupyter notebooks in the documentation.

To build the documentation, run sphinx-autobuild using:

uv run sphinx-autobuild docs docs/_build/html

This will build the documentation and serve it on a local http server which listens for changes and automatically rebuilds.

Documentation from the main branch and tagged releases is automatically built and hosted on readthedocs.

Acknowledgments

This document is based off of the guidelines from the sparse project.