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
    ./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 <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.

Versioning
----------

Bump the version using ``uv version --bump``:

.. code-block:: bash

    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
