Contributing
============

To report unexpected behavior, open an
`issue <https://github.com/rjmalves/cfinterface/issues>`_ in the repository.
When doing so, it is recommended to provide basic information (Python version,
operating system) along with a code snippet that allows the problem to be
reproduced. If you have found a possible fix for an existing issue,
`pull requests <https://github.com/rjmalves/cfinterface/pulls>`_
are welcome. In that case, please review the content of this page before
submitting your contribution.


Development Environment Setup
-------------------------------

To install the development dependencies, run the commands below:

.. code-block:: bash

    git clone https://github.com/rjmalves/cfinterface.git
    cd cfinterface
    uv sync --extra dev
    uv run pre-commit install


Pre-commit Hooks
-----------------

The project uses `pre-commit <https://pre-commit.com/>`_ to automatically
enforce code quality before each commit. Three hooks are configured:

- **ruff** (v0.9.10): linter with automatic fixes (``--fix``)
- **ruff-format** (v0.9.10): code formatting
- **mypy** (v1.19.1): static type checking, applied only to the
  ``cfinterface/`` directory

To run all hooks manually against all files:

.. code-block:: bash

    uv run pre-commit run --all-files


Code Conventions
-----------------

The project uses ``ruff`` for linting and formatting, and ``mypy`` for static
typing. To run the checks manually:

.. code-block:: bash

    uv run ruff check ./cfinterface
    uv run ruff format --check ./cfinterface
    uv run mypy ./cfinterface

These same checks are run in the CI workflows. For a version to be published
successfully, all requirements must be met.


Tests
------

The adopted testing framework is `pytest <https://docs.pytest.org/en/stable/>`_.

To run all tests:

.. code-block:: bash

    uv run pytest ./tests

To run only the performance tests with
`pytest-benchmark <https://pytest-benchmark.readthedocs.io/>`_:

.. code-block:: bash

    uv run pytest ./tests --benchmark-only

To check test coverage with
`pytest-cov <https://pytest-cov.readthedocs.io/>`_:

.. code-block:: bash

    uv run pytest ./tests --cov=cfinterface


Documentation
--------------

The documentation is built with `Sphinx <https://www.sphinx-doc.org/>`_ and the
`Furo <https://pradyunsg.me/furo/>`_ theme. To generate the documentation
locally:

.. code-block:: bash

    uv run sphinx-build -W -b html docs/source docs/build/html

.. note::

    The content generated by the build **must not be committed** to the
    repository. Artifacts are built and published automatically by the
    `GitHub Actions <https://github.com/features/actions>`_ workflows on
    every change to the ``main`` branch.