Skip to content

Latest commit

 

History

History
197 lines (132 loc) · 6.92 KB

CONTRIBUTING.rst

File metadata and controls

197 lines (132 loc) · 6.92 KB

Contributing

Introduction

First of all, thank you for considering contributing to the QENS models' library. Contributions are welcome from the community.

This document describes some guidelines that are intended to help to communicate with the developers' team, so that it can address your issue, assess your changes and help you finalize your pull requests.

Installation

In order to contribute to the development of the library, in a terminal

  • activate your virtual environment (see the installation )
  • run:
python -m pip install -e  '\path_to_QENS_library/.[dev]'

This will install what is needed to

  • build the documentation
  • run the unit tests and doc tests and analyse the code
  • run the examples (Jupyter notebooks)

Ground rules

If you have direct contributions you would like to be considered for incorporation into the project you can fork this repository and submit a pull request for review.

Contributors feeling unsure or inexperienced about contributing to an open-source repository are referred to this tutorial.

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub

People interested can contribute to the project in different ways, for example, by:

  1. adding QENS models
  2. adding new examples of fitting using some of the QENS models and the fitting engine of their choice

New QENS models

  • Contributed models should be written in Python 3.x.
  • For each new model, a Python script should be provided alongside some documentation and tests.
  • Once ready, you need to upload the Python source code files to the git repository by submitting a pull request.

Physical units

For information about unit conversion, please refer to the jupyter notebook called Convert_units.ipynb in the tools folder.

Python script

  • It should be placed in the QENS models folder. The associated Python script for the tests should be placed in the tests folder and added to the list in run_tests.sh.
  • Each function should have a docstring specifying its name, parameters, a short description and some examples. These examples will be used when running doctest. Please refer to the existing models for help. A more general template for docstring can be found here.
  • And before submitting your pull request, check that your script, tests and built of the documentation run on your machine. Please also run flake8 to check your code matches the project style (by running, for example, python -m flake8 new_python_script.py).

Documentation

  • For the QENS models' library, the documentation is built using Sphinx.
  • The related files are located in the docs folder.
  • In addition, as mentioned in the previous section, each model should contain a self-contained description.

Building the documentation locally

In a terminal, run

python -m sphinx path_to_docs_folder build_folder

where build_folder is where you want to build the documentation of the library.

Tests

The script to run the tests is located in the tools folder. These tests require the installation of doctest and unittest.

In a terminal, move to the tools directory and run

./run_tests.sh

New examples

  • Contributed examples should use jupyter <https://github.com/QENSlibrary/QENSmodels/labels/jupyter>`_ notebooks (preferred) or Python scripts.
  • Please add a maximum of information about the case being described:
    • physical model
    • reference to publications (if any)
    • steps leading to the final results (reduction, convolution of different models, normalization...)
    • choice of minimizer and link to its documentation
  • If additional reference datasets are required, they can be stored in the /examples/data folder. But the preferred option is to generate these reference data on the fly in the notebook or script without creating any permanent external file.
  • If additional Python modules are used in the new notebook or script, please add them to the list of requirements in pyproject.toml in the appropriate sections (dependencies or optional-dependencies).

Other issues

  • `question <https://github.com/QENSlibrary/QENSmodels/labels/question>`_ and `Enhancement <https://github.com/QENSlibrary/QENSmodels/labels/enhancement>`_ related to the library can be asked on the issues page.
  • Before creating a new issue, please take a moment to search and make sure a similar issue does not already exist. If one does exist, you add a comment to it; most simply even with just a 👍 to show your support for that issue.
  • If you find any bugs, please report them by submitted a new issue labelled as `bug <https://github.com/QENSlibrary/QENSmodels/labels/bug>`_ . The more details you can provide the better. If you know how to fix the bug, please open an issue first and then submit a pull request.
  • `good-first-issue <https://github.com/QENSlibrary/QENSmodels/labels/good%20first%20issue>`_ issues are particularly appropriate if it is your first contribution.
  • `help-wanted <https://github.com/QENSlibrary/QENSmodels/labels/help%20wanted>`_ contains a task that you can contribute to. We especially encourage you to do so if you feel you can help.