Contributing

Thank you for considering contributing to ILTpy. This document provides guidelines for contributing effectively and maintaining the consistency of the project. Please read these guidelines before submitting code, documentation, or other changes.

General guidelines

  • ILTpy is written in Python, therefore, code contributions must be in Python.

  • Inclusion of new dependencies should be minimized and if included, should lead to an improvement in performance, functionality or ease of use.

  • Ensure compatibility with the project’s existing dependencies and licensing terms.

  • Scientific justification must be provided for changing the mathematical or numerical structure of the library.

  • Changes to algorithmic flow should lead to to an improvement in performance, functionality or ease of use.

Coding style

  • Follow the PEP 8 guidelines for Python.

  • Using a python linter e.g. Ruff is recommended.

  • Docstrings must be provided in the NumPy style format :

"""
Brief summary of the function.

Parameters
----------
param_name : param_type
    Description of the parameter.

Returns
-------
return_type
    Description of the return value.

Raises
------
ExceptionType
    Condition that raises the exception.
"""

Testing Requirements

  • All new functionality must include tests written within the pytest framework.

  • If applicable, test functions must contain docstrings that briefly summarizes the purpose of the test.

  • Use pytest to verify the functioning of the library locally before submitting a Merge request and ensure that original tests pass after development.

Documentation

  • Documentation must be built using Sphinx.

  • All new functionalities or features must be documented and where applicable, should include examples.

  • All new functions must have docstrings and should be properly commented.

Development workflow

  1. Fork the ILTpy repository and then clone your fork locally.

  2. Create a python virtual environment (optional but recommended).

  3. Navigate to your local directory where the repository was cloned and the setup.py file is present. While in the folder, install ILTpy for development by running the following command in a terminal :

    python -m pip install -e ".[develop]"

    Along with the installation of ILTpy in an editable mode, this will install pytest and sphinx required for testing ILTpy and building documentation respectively.

  4. Use pytest to check your local installation of ILTpy by running in a terminal :

    python -m pytest -v tests/ilt_test.py

  5. Develop.

  6. If applicable, update the documentation and in case of changes, ensure that the documentation renders without errors when building with sphinx locally.

  7. Run pytest again to ensure that your changes pass the original tests and any new tests that were added.

  8. Push your changes to the forked repository.

  9. Submit a merge request to the ILTpy repository. Merge requests must be made to the development branch and not to the main branch. Describe the changes you have made, information about any new dependency and mention any related issue.

  10. Your merge request will trigger test pipelines. Your changes will be merged by one of the core team members of ILTpy, provided the pipelines pass. Thank you for contributing to ILTpy.

Reporting bugs

Please open an issue on the ILTpy repository or contact the ILTpy team.