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:

.. code-block:: bash

    # 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
    uv run oi docs --build

    # format your code
    ./scripts/format

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

    # 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 <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`_ 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.
