=========================
Contributing to PyNitride
=========================

Getting started
=================

To become a contributor, first `fork the repository <https://github.com/samueljamesbader/PyNitride/fork>`_
then follow the :ref:`build-from-source instructions <building-from-source>`,
except use your forked repository URL when cloning instead of the main repository URL.

Dependency management
=======================
The dependencies are defined by ``pyproject.toml`` and locked in ``requirements.txt``.

To regenerate the locked dependencies after changing ``pyproject.toml``, run:

.. code-block:: bash

   pip-compile --no-strip-extras --no-annotate --no-allow-unsafe --no-header --extra dev -o requirements.txt pyproject.toml

(To update the dependencies to their latest versions, add an ``--upgrade`` flag, or e.g. ``--upgrade-package numpy`` to only upgrade a specific package.)

Then install the new dependencies with

.. code-block:: bash

   pip install -r requirements.txt

Note that the CI `Tests` job checks that regenerating the locked dependencies from ``pyproject.toml`` matches the existing ``requirements.txt``,
so if you change ``pyproject.toml`` you must also regenerate ``requirements.txt``.  (This regeneration references
the existing ``requirements.txt`` so it should not fail just because a newer version of a dependency was released.)

Tests
========
Tests include unit tests, literature value tests, and a set of example simulations that are run and compared to "golden" output files.

CI
************
The Tests workflow (``.github/workflows/tests.yml``) runs the unit tests and example tests on every push and pull request, and will fail if any of the tests fail.

Golden files
************
These golden files were generated by running the examples and saving the output, and are included in the repository in the ``tests/examples/goldens`` directory.
When adding a new example, you should create a test function for it in ``test_examples.py`` (under ``tests/examples/``) following the pattern of e.g. ``test_hemt_example()``.

Then to generate the golden file for a new example, you can simply run ``test_examples.py`` with the name of the example function, e.g. ``python test_examples.py test_hemt_example``.

Documentation
=============
The source files are in the ``docs/`` and ``docs/manual/`` directories.
The root toctree is in ``docs/index.rst``.
You can add new pages to the manual by creating new ``.rst`` files in ``docs/manual/`` and adding them to the toctree in ``docs/index.rst``.

Building
************
The documentation is built using Sphinx, just run ``python docs/document.py``,
which will generate the API reference and build the HTML files in the ``docs/build/html/`` directory.

Deploying documentation
***********************
Documentation (such as `latest <https://pynitride.readthedocs.io/en/latest/>`_) is hosted on `Read the Docs <https://readthedocs.org/projects/pynitride/>`_ and rebuilds automatically on every push to ``main``.

Distribution
=============

Wheels
******
PyNitride contains Cython extensions and must be distributed as pre-built binary wheels.
Wheels are built using `cibuildwheel <https://cibuildwheel.pypa.io>`_ for the following platforms:

.. list-table::
   :header-rows: 1

   * - Runner
     - Wheel
   * - ``ubuntu-latest``
     - ``manylinux_x86_64``
   * - ``ubuntu-24.04-arm``
     - ``manylinux_aarch64``
   * - ``windows-latest``
     - ``win_amd64``
   * - ``windows-11-arm``
     - ``win_arm64``
   * - ``macos-latest``
     - ``macosx_arm64``

The cibuildwheel configuration lives in ``pyproject.toml`` under ``[tool.cibuildwheel]``.
After building each wheel, cibuildwheel installs it into a fresh virtual environment and
runs the full test suite to verify the wheel is functional.

CI
************
The Build Tests workflow (``.github/workflows/build_tests.yml``) runs on every push to,
or pull request targeting, ``dev``, ``main``, or any ``release/**`` branch.  It builds wheels for all five platforms
and runs the tests inside each installed wheel.

Publishing to PyPI
**********************
The PyPI workflow (``.github/workflows/pypi.yml``) publishes to the
`PyNitride PyPI project <https://pypi.org/project/pynitride/>`_ when a tag of
the form ``vX.X.X`` is pushed to ``main``.

To cut a release:

1. Bump ``__version__`` in ``src/pynitride/__init__.py`` to the intended version, e.g. ``"0.2.0"``.
2. Commit and push to ``main``.
3. Tag the commit with the **matching** version and push the tag — the workflow enforces that the tag and ``__version__`` agree::

      git tag vX.Y.Z
      git push origin vX.Y.Z

The workflow will build wheels for all five platforms and, once all builds pass, publish
them to PyPI.  To install from PyPI for verification::

   pip install pynitride

Pull requests
=================
When contributing to the project, please `open a pull request from your fork <https://medium.com/swlh/forks-and-pull-requests-how-to-contribute-to-github-repos-8843fac34ce8>`_ with a clear description of the changes and why they are needed.
Pull requests from forks should apply to the ``dev`` branch, not ``main``!  Once tested on ``dev``, the changes can be merged into ``main`` by the maintainers.