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

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:

.. code-block:: bash

    # 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