|
| 1 | +======================= |
| 2 | +Contribution guidelines |
| 3 | +======================= |
| 4 | + |
| 5 | +What to work on? |
| 6 | +---------------- |
| 7 | + |
| 8 | +You are welcome to propose and contribute new ideas. |
| 9 | +We encourage you to `open an issue <https://github.com/quantmetry/qolmat/issues>`_ so that we can align on the work to be done. |
| 10 | +It is generally a good idea to have a quick discussion before opening a pull request that is potentially out-of-scope. |
| 11 | + |
| 12 | +Fork/clone/pull |
| 13 | +--------------- |
| 14 | + |
| 15 | +The typical workflow for contributing to `Qolmat` is: |
| 16 | + |
| 17 | +1. Fork the `main` branch from the `GitHub repository <https://github.com/quantmetry/qolmat>`_. |
| 18 | +2. Clone your fork locally. |
| 19 | +3. Commit changes. |
| 20 | +4. Push the changes to your fork. |
| 21 | +5. Send a pull request from your fork back to the original `main` branch. |
| 22 | + |
| 23 | +Local setup |
| 24 | +----------- |
| 25 | + |
| 26 | +We encourage you to use a virtual environment. You'll want to activate it every time you want to work on `Qolmat`. |
| 27 | + |
| 28 | +You can create a virtual environment via `conda`: |
| 29 | + |
| 30 | +.. code:: sh |
| 31 | +
|
| 32 | + $ conda env create -f environment.dev.yml |
| 33 | + $ conda activate env_qolmat_dev |
| 34 | +
|
| 35 | +If you need to use tensorflow, enter the command: |
| 36 | + |
| 37 | +.. code:: sh |
| 38 | +
|
| 39 | + $ pip install -e .[tensorflow] |
| 40 | +
|
| 41 | +Once the environment is installed, pre-commit is installed, but need to be activated using the following command: |
| 42 | + |
| 43 | +.. code:: sh |
| 44 | +
|
| 45 | + $ pre-commit install |
| 46 | + $ pre-commit install-hooks |
| 47 | +
|
| 48 | +Documenting your change |
| 49 | +----------------------- |
| 50 | + |
| 51 | +If you're adding a class or a function, then you'll need to add a docstring with a doctest. We follow the `numpy docstring convention <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`_, so please do too. |
| 52 | +Any estimator should follow the [scikit-learn API](https://scikit-learn.org/stable/developers/develop.html), so please follow these guidelines. |
| 53 | + |
| 54 | +Updating changelog |
| 55 | +------------------ |
| 56 | + |
| 57 | +You can make your contribution visible by : |
| 58 | + |
| 59 | +1. adding your name to the Contributors sections of `AUTHORS.rst <https://github.com/quantmetry/qolmat/blob/main/AUTHORS.rst>`_ |
| 60 | +2. adding a line describing your change into `HISTORY.rst <https://github.com/quantmetry/qolmat/blob/main/HISTORY.rst>`_ |
| 61 | + |
| 62 | +Testing |
| 63 | +------- |
| 64 | + |
| 65 | +Pre-commit |
| 66 | +^^^^^^^^^^ |
| 67 | + |
| 68 | +These tests absolutely have to pass. |
| 69 | + |
| 70 | +.. code:: sh |
| 71 | +
|
| 72 | + $ pre-commit run --all-files |
| 73 | +
|
| 74 | +Static typing |
| 75 | +^^^^^^^^^^^^^ |
| 76 | + |
| 77 | +These tests absolutely have to pass. |
| 78 | + |
| 79 | +.. code:: sh |
| 80 | +
|
| 81 | + $ mypy qolmat |
| 82 | +
|
| 83 | +Unit test |
| 84 | +^^^^^^^^^ |
| 85 | + |
| 86 | +These tests absolutely have to pass. |
| 87 | +The coverage should on new features must be above 95%. |
| 88 | + |
| 89 | +.. code:: sh |
| 90 | +
|
| 91 | + $ pytest -vs --cov-branch --cov=qolmat --pyargs tests --cov-report term-missing |
0 commit comments