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