.. _developerGuide:

###############
Developer Guide
###############

This section includes information for developers who want to contribute to the project. It includes information about the project structure, how to run the tests, and how to build the documentation. It also includes information about the project's coding style and how to contribute to the project.

*****************
Coding Guidelines
*****************

The project follows the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ coding style. The project uses `setuptools <https://setuptools.readthedocs.io/en/latest/>`_ for packaging and distribution. The project uses `Sphinx <http://www.sphinx-doc.org/en/master/>`_ for documentation. The project uses `pytest <https://docs.pytest.org/en/latest/>`_ for testing. The project uses `Gitflow <http://nvie.com/posts/a-successful-git-branching-model/>`_ for branching.

In order to contribute to the project, it is important to follow the coding style and guidelines used by the project, therefore please read ALL of the following sections carefully.

*****************
How to Contribute
*****************

For any contributor willing to contribute to the project, it is important to understand the branching model used by the project. The project uses the `Gitflow <http://nvie.com/posts/a-successful-git-branching-model/>`_ branching model. Pull requests should stay small and reviewer-readable. In order to contribute to the project please follow the following steps:


    #. Fork the project on Github. (not necessary if you are a member of the project)

    #. Clone your fork locally:
    
        .. code:: bash

            $ git clone https://github.com/MolarVerse/PQAnalysis.git

    #. Initialize git flow with the following settings (if not specified default settings are used)

        .. code:: bash

            [master] main
            [develop] dev
            [version tag prefix] v

    #. Create a feature branch for your contribution:
    
        .. code:: bash

            $ git flow feature start <feature_branch_name>


    #. Commit your changes to your feature branch and publish your feature branch:
    
        .. code:: bash

            $ git add <files>
            $ git commit -m "fix: describe the bug fix"
            $ git flow feature publish <feature_branch_name>
    
    #. Create a pull request on Github.

    #. Use a short Conventional Commits title for the pull request, for example ``feat: add a new analysis command`` or ``fix(io): handle missing trajectory data``. This title is validated by CI.

    #. Once your pull request is approved and all required checks pass, it will be merged into the develop branch. If the pull request is squash merged, use the pull request title as the squash commit message.

    #. Optional: enable the local commit-message hook for earlier feedback:

        .. code:: bash

            $ git config core.hooksPath .githooks

*************
Documentation
*************

Please make sure that all code is well documented. The project uses `Sphinx <http://www.sphinx-doc.org/en/master/>`_ for documentation. The documentation of this webpage is autogenerated from the docstrings of the implemented code, thus it is important to make sure that all docstrings are correct and informative. 

.. attention::

    The project uses `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`_ for docstring formatting. Please make sure that all docstrings are formatted correctly.

In order to install all the dependencies required for building the documentation, use the following command:

.. code:: bash

    $ pip install -e ".[docs]" # install the project with the documentation dependencies

To build the documentation, use the following command:

.. code:: bash

    $ cd docs

    $ make html

In order to view the documentation, open the following file in a web browser:

.. code:: bash

    $ open build/html/index.html

For the CI/CD pipeline, the a documentation coverage of 99.9% is required. Please make sure that all implemented features are correctly documented. To evaluate the documentation coverage, use the following command:

.. code:: bash

    $ docstr-coverage PQAnalysis

*******
Testing
*******

The project uses `pytest <https://docs.pytest.org/en/latest/>`_ for testing. Before creating a pull request, please make sure that all tests pass and ensure a high quality of code coverage. In order to run the tests, use the following command:

.. code:: bash

    $ pip install -e ".[test]" # install the project with the test dependencies

    $ python -m pytest

The testing framework will run all tests and provide automatically generated coverage reports. Not only should all tests pass, but the coverage should be as close to 100% as possible. Furthermore, the project automatically uses doctest, so please make sure that all examples included in the doc strings of the implemented features are correct otherwise the tests will fail.

Last, if any additional dependencies are required for testing, please add them to the ``pyproject.toml`` file under the ``[project.optional-dependencies]`` section.

**********************
Performance Validation
**********************

File-backed VACF, MSD, RDF and momentum analyses use bounded compiled fast
paths. A batch path must preserve the numeric operation order of its streaming
fallback and must return to that fallback when the configured memory limit is
exceeded. Parallel work is restricted to independent lag ranges, frames or
private integer histograms; floating-point reductions within one legacy result
must not be reordered.

Install the benchmark dependency and run the focused benchmark suite with:

.. code:: bash

    $ pip install -e ".[test,benchmark]"
    $ pytest -c benchmarks/pytest.ini benchmarks --benchmark-only

Store a baseline with ``--benchmark-json=baseline.json`` and compare a changed
branch with ``--benchmark-compare=baseline.json``. Runtime assertions do not
belong in CI because host load is variable. Every optimization must instead
pass the compiled and fallback tests plus the relevant fixed-bit legacy oracle
before its benchmark result is considered.