Contributing

Developer Guide

Setup

This project uses hatch to manage the development environment and build and publish releases. Make sure hatch is installed first:

$ pip install hatch

Now you can enter the development environment using:

$ hatch shell

This will install development dependencies in an isolated environment and drop you into a shell (use exit to leave).

Pre-commit

Use pre-commit to run linting, type-checking, and formatting:

$ hatch run pre-commit run --all-files

...or install it to run automatically before every commit with:

$ hatch run pre-commit install

You can run pre-commit hooks separately and pass additional arguments to them. For example, to run ruff-format on a single file:

$ hatch run pre-commit run ruff-format --files=src/sknnr/_base.py

Testing

Unit tests are not run by pre-commit, but can be run manually using hatch scripts:

$ hatch run test:all

Measure test coverage with:

$ hatch run test:coverage

Any additional arguments are passed to pytest. For example, to run a subset of tests matching a keyword:

$ hatch run test:all -k gnn

Documentation

Documentation is built with mkdocs. During development, you can run a live-reloading server with:

$ hatch run docs:serve

The API reference is generated from Numpy-style docstrings using mkdocstrings. New classes can be added to the API reference by creating a new markdown file in the docs/pages/api directory, adding that file to the nav tree in docs/mkdocs.yml, and including the docstring in the markdown file:

::: sknnr.module.class

Whenever the docs are updated, they will be automatically rebuilt and deployed by ReadTheDocs. Build status can be monitored here.

Releasing

First, use hatch to update the version number in a new release branch and merge into main.

$ hatch version [major|minor|patch|alpha|beta|rc|post|dev]

Checkout main and confirm that it is up-to-date with the remote, including the bumped version. Finally, create and push the release tag.

$ git checkout main
$ git pull
$ git tag "$(hatch version)"
$ git push --tags

Pushing the updated tag will trigger a workflow that publishes the release to PyPI.