Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
111 lines (78 loc) · 2.76 KB

CONTRIBUTING.md

File metadata and controls

111 lines (78 loc) · 2.76 KB

See the Scientific Python Developer Guide for a detailed description of best practices for developing scientific packages.

Commit and pull request expectations

  • Every commit should reference the issue number with which it is associated.
  • Commits should be reasonably granular and semantically atomic.
  • Pull requests should not be squashed upon merging.

Quick development

The fastest way to start with development is to use nox. If you don't have nox, you can use pipx run nox to run it without installing, or pipx install nox. If you don't have pipx (pip for applications), then you can install with pip install pipx (the only case were installing an application with regular pip is reasonable). If you use macOS, then pipx and nox are both in brew, use brew install pipx nox.

To use, run nox. This will lint and test using every installed version of Python on your system, skipping ones that are not installed. You can also run specific jobs:

$ nox -s lint  # Lint only
$ nox -s tests  # Python tests
$ nox -s docs -- --serve  # Build and serve the docs
$ nox -s build  # Make an SDist and wheel

Nox handles everything for you, including setting up an temporary virtual environment for each run.

Setting up a development environment manually

You can set up a development environment by running:

python3 -m venv .venv
source ./.venv/bin/activate
python -m pip install -v -e '.[test]'

The test extra installs the optional feature dependencies exercised by the test suite, plus pytest tooling. If you also need development-only DVC tooling, install .[test,dev].

If you have the Python Launcher for Unix, you can instead do:

py -m venv .venv
py -m pip install -v -e '.[test]'

Post setup

You should prepare pre-commit, which will help you by checking that commits pass required checks:

pip install pre-commit # or brew install pre-commit on macOS
pre-commit install # Will install a pre-commit hook into the git repo

You can also/alternatively run pre-commit run (changes only) or pre-commit run --all-files to check even without installing the hook.

Testing

Use pytest to run the unit checks:

pytest

Coverage

Use pytest-cov to generate coverage reports:

pytest --cov=openlifu

Building docs

You can build the docs using:

nox -s docs

You can see a preview with:

nox -s docs -- --serve

Pre-commit

This project uses pre-commit for all style checking. While you can run it with nox, this is such an important tool that it deserves to be installed on its own. Install pre-commit and run:

pre-commit run -a

to check all files.