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

Requirements
------------

- Python **>= 3.9** - minimal runtime requirement for the project.
- CPU architecture: **x86_64**.
- Zig == **0.14.1** - required for building native libraries.

.. important::
    Building the documentation locally requires **Python >= 3.11**.

Quickstart
----------

1. Fork the repository.
2. Clone the repository and enter project directory.
3. Create and activate a virtual environment.
4. Install developer dependencies:

   .. code-block:: bash

      pip install -r dev-requirements.txt

5. Install the package in editable mode:

   .. code-block:: bash

      pip install -e .

   .. note::
      Installing in editable mode will automatically trigger a build of the native
      libraries in **release-mode**.
      It is recommended to rebuild the libraries manually afterwards in **debug-mode**, following
      the steps in :ref:`Building native libraries (Zig)`.
      Otherwise, you are ready to go.

Building native libraries (Zig)
-------------------------------

1. Install Zig 0.14.1 (download from the Zig website or use your package manager).
2. Verify Zig's version:

   .. code-block:: bash

      zig version

3. Build the native libraries:

   .. code-block:: bash

      python build_libs.py

   .. note::
      If you make changes to the **C-API**, you must rebuild the libraries afterwards.

Running tests
-------------

1. Run tests:

   .. code-block:: bash

      pytest tests

Quality checks
--------------

1. Run pylint:

   .. code-block:: bash

      pylint zyntex

2. Run pyright:

   .. code-block:: bash

      pyright zyntex

Commit & PR guidelines
----------------------

- Keep PRs small and focused — one logical change per PR.
- Ensure all tests pass locally before pushing.
- Provide a short description of what the PR changes and why.
- Link related issues or discussions in the PR description.

Appendix: Recommended local workflow
-----------------------------------

1. Create branch.
2. Implement change + add tests.
3. Run tests and quality checks.
4. Run docs build if your change affects documentation.
5. Push branch and open PR.