Contributing

To contribute, you must open a PR, write code that passes all automated checks (runnable with ./scripts/all-checks), and have at least one other person approve your changes.

For example, using the gh command-line tool:

# get the repo
gh repo clone opportunityinsights/oi-tools
cd oi-tools

# make a new branch
git branch new-feature
git switch new-feature

# make your changes in vscode
code .

# build the docs and make sure they look okay on your computer
./scripts/docs

# fix linting and formatting issues
./scripts/fix

# make sure your changes pass the automated checks (formatting, linting, tests, etc.)
# make sure this passes before opening a PR!
./scripts/check

# create a pr in your browser
gh pr create --web

Docs

All user-facing function must be documented using the Numpy docstring format. (See existing functions or this page for examples.) Nontrivial functions—e.g. those with more than two arguments or implementations of more than a dozen lines—should also have usage examples.

Versioning

Bump the version using uv version --bump:

uv version --bump minor   # new features
uv version --bump patch   # bug fixes

Use patch version bumps for:

  • Bug fixes

  • Documentation improvements

  • Internal refactors with no API changes

Use minor version bumps for:

  • New user-facing functions or parameters

  • Deprecations

  • Any change that affects public behavior or output

Tests

Use ./scripts/test to run the entire test suite. You’ll need Docker installed and running to launch the container containing the PBS server.

On Apple silicon, this can be set up with the following snippet:

# install deps
# colima is an open-source docker runtime that's much lighter weight than Docker Desktop
# the last two deps are necessary to emulate x86 cpu architecture on the apple ARM chips
brew install docker docker-compose colima lima-additional-guestagents qemu

# start docker daemon
colima start --arch x86_64 --vm-type=vz --vz-rosetta