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

Any help is welcome -- including constructive criticism. Feel free
to clone the repository, run it, and open merge requests or issues.

Standards
---------

The project sticks to a few standards so the code stays consistent
and merges painlessly.

Tooling:

* `Ruff <https://docs.astral.sh/ruff/>`_ -- lint and format. Configured
  in ``pyproject.toml``; ``migrations/`` is excluded.
* `uv <https://docs.astral.sh/uv/>`_ -- dependency management.
  ``pyproject.toml`` is the source of truth; ``requirements`` and
  ``requirements_dev`` are generated from it.
* `Docker <https://github.com/docker>`_ -- everything runs in
  containers.

Code style:

* Python ``>= 3.13``.
* Prefer the simplest solution that solves the problem.
* Prefer dataclasses or Pydantic models over raw ``dict`` for
  structured data.
* Prefer ``f-strings`` over ``%`` / ``.format()``.
* Prefer ``pathlib`` over ``os.path``.
* Use docstrings on functions, classes and methods (autodoc renders
  them in these docs).

Updating dependencies
---------------------

Edit ``pyproject.toml``, then refresh the lockfile and re-export the
requirements files:

.. code-block:: bash

    # 1. Resolve and update uv.lock from pyproject.toml.
    $ uv lock

    # 2. Export uv.lock into the plain requirements files the
    #    Dockerfile consumes via `pip install -r`.
    $ uv export --no-hashes --no-annotate --no-dev -o app/requirements
    $ uv export --no-hashes --no-annotate -o app/requirements_dev

``uv.lock`` is the single source of truth: ``uv sync`` (used by
contributors) and the exported ``requirements`` files (used by the
Docker image) both derive from it, so they cannot drift.

Commit ``pyproject.toml``, ``uv.lock``, ``app/requirements`` and
``app/requirements_dev`` together.

Rebuild the image:

.. code-block:: bash

    $ docker compose -f compose.dev.yaml build

Updating documentation
----------------------

Documentation lives in ``docs/`` and is built with Sphinx:

.. code-block:: bash

    $ cd docs
    $ uv run make clean html

Output ends up in ``docs/build/html/index.html``. To validate cleanly
(no warnings) before opening a merge request:

.. code-block:: bash

    $ cd docs
    $ sphinx-build -W -b html source build/html

Whenever a feature is added or changed, update the relevant page in
``docs/source/modules/`` and -- if architecture-level concepts
shift -- the relevant page under ``docs/source/architecture/``.

Co-developed libraries
----------------------

Some functionality lives in sibling libraries that are co-developed
with this project:

* `Rug <https://gitlab.com/imn1/rug>`_ -- stock-market data scrapers.
* `Karpet <https://gitlab.com/imn1/karpet>`_ -- cryptocurrency data
  scrapers.

If you fix a scraper there, you'll typically also need a release of
the library and a dependency bump here.