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

Setting up the environment
--------------------------

.. code-block:: bash

   bash scripts/setup_env.sh
   source .venv/bin/activate

Recommended workflow
--------------------

1. Create a branch off ``main``: ``git checkout -b feat/my-feature``.
2. Write code and add tests in ``tests/``.
3. Run quality checks before pushing:

   .. code-block:: bash

      ruff check src tests
      mypy src
      pytest

4. Rebuild the docs and check that they compile without warnings:

   .. code-block:: bash

      cd docs && make clean html

Conventions
-----------

* Magnetic sign convention: ``H = +Σ_{i≠j} J_ij S_i·S_j``  (AFM > 0).
* Type hints are required on the public API.
* Docstrings in Google or NumPy style (Napoleon accepts both).
* ``ruff`` settings: 100-char line length, rules ``E F W I N UP B C4 SIM``.
* Unit tests for every new feature or bug fix.
* Physics-style names (``JS2``, ``Jq``, ``q_cart``) are allowed —
  ``ruff`` ignores ``N803`` and ``N806``.