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 coding style. The project uses setuptools for packaging and distribution. The project uses Sphinx for documentation. The project uses pytest for testing. The project uses Gitflow 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 branching model. Pull requests should stay small and reviewer-readable. In order to contribute to the project please follow the following steps:

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

  2. Clone your fork locally:

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

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

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

  4. Create a feature branch for your contribution:

    $ git flow feature start <feature_branch_name>

  5. Commit your changes to your feature branch and publish your feature branch:

    $ git add <files>
$ git commit -m "fix: describe the bug fix"
$ git flow feature publish <feature_branch_name>

  6. Create a pull request on Github.

  7. 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.

  8. 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.

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

    $ git config core.hooksPath .githooks

Documentation

Please make sure that all code is well documented. The project uses Sphinx 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 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:

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

To build the documentation, use the following command:

$ cd docs

$ make html

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

$ 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:

$ docstr-coverage PQAnalysis

Testing

The project uses pytest 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:

$ 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.