|
| 1 | +# How to contribute |
| 2 | + |
| 3 | +First of all, thank you for considering contributing to `plotly-resampler`.<br> |
| 4 | +It's people like you that will help make `plotly-resampler` a great toolkit. |
| 5 | + |
| 6 | +As usual, contributions are managed through GitHub Issues and Pull Requests. |
| 7 | + |
| 8 | +We are welcoming contributions in the following forms: |
| 9 | +* **Bug reports**: when filing an issue to report a bug, please use the search tool to ensure the bug hasn't been reported yet; |
| 10 | +* **New feature suggestions**: if you think `plotly-resampler` should include a new feature, please open an issue to ask for it (of course, you should always check that the feature has not been asked for yet :). Think about linking to a pdf version of the paper that first proposed the method when suggesting a new algorithm. |
| 11 | +* **Bugfixes and new feature implementations**: if you feel you can fix a reported bug/implement a suggested feature yourself, do not hesitate to: |
| 12 | + 1. fork the project; |
| 13 | + 2. implement your bugfix; |
| 14 | + 3. submit a pull request referencing the ID of the issue in which the bug was reported / the feature was suggested; |
| 15 | + |
| 16 | +When submitting code, please think about code quality, adding proper docstrings, and including thorough unit tests with high code coverage. |
| 17 | + |
| 18 | + |
| 19 | +## How to develop locally |
| 20 | + |
| 21 | +*Note: this guide is tailored to developers using linux* |
| 22 | + |
| 23 | +The following steps assume that your console is at the root folder of this repository. |
| 24 | + |
| 25 | +### Create a new (poetry) Python environment |
| 26 | + |
| 27 | +It is best practice to use a new Python environment when starting on a new project. |
| 28 | + |
| 29 | +We describe two options; |
| 30 | + |
| 31 | +<details> |
| 32 | +<summary><i>Advised option</i>: using poetry shell</summary> |
| 33 | +For dependency management we use poetry (read more below).<br> |
| 34 | +Hence, we advise to use poetry shell to create a Python environment for this project. |
| 35 | + |
| 36 | +1. Install poetry: https://python-poetry.org/docs/#installation <br> |
| 37 | + (If necessary add poetry to the PATH) |
| 38 | +2. Create & activate a new python environment: <code>poetry shell</code> |
| 39 | + |
| 40 | +After the poetry shell command your python environment is activated. |
| 41 | +</details> |
| 42 | + |
| 43 | +<details> |
| 44 | +<summary><i>Alternative option</i>: using python-venv</summary> |
| 45 | +As alternative option, you can create a Python environment by using python-venv |
| 46 | + |
| 47 | +1. Create a new Python environment: <code>python -m venv venv</code> |
| 48 | +2. Activate this environment; <code>source venv/bin/activate</code> |
| 49 | +</details> |
| 50 | + |
| 51 | +Make sure that this environment is activated when developing (e.g., installing dependencies, running tests). |
| 52 | + |
| 53 | + |
| 54 | +### Installing & building the dependencies |
| 55 | + |
| 56 | +We use [poetry](https://python-poetry.org/) as dependency manager for this project. |
| 57 | +- The dependencies for installation & development are written in the [pyproject.toml](pyproject.toml) file (which is quite similar to a requirements.txt file). |
| 58 | +- To ensure that package versions are consistent with everyone who works on this project poetry uses a [poetry.lock](poetry.lock) file (read more [here](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock)). |
| 59 | + |
| 60 | +To install the requirements |
| 61 | +```sh |
| 62 | +pip install poetry # install poetry (if you do use the venv option) |
| 63 | +poetry install # install all the dependencies |
| 64 | +poetry build # build the underlying C code |
| 65 | +``` |
| 66 | + |
| 67 | +<details> |
| 68 | + <summary> |
| 69 | + <b>How to resolve the following error when running build.py:</b><br> |
| 70 | + <code>Unable to build the "plotly_resampler.aggregation.algorithms.lttbc" C extension; will use the slower python fallback. <br> |
| 71 | + command 'x86_64-linux-gnu-gcc' failed: No such file or directory |
| 72 | + </code> |
| 73 | + </summary> |
| 74 | + |
| 75 | + To resolve this error we suggest to install some additional packages as no gcc (C compiler was found on your PC): |
| 76 | + ```sh |
| 77 | + sudo apt-get install build-essential libssl-dev libffi-dev python-dev |
| 78 | + ``` |
| 79 | + |
| 80 | +</details> |
| 81 | + |
| 82 | +### Running the tests (& code coverage) |
| 83 | + |
| 84 | +You can run the test with the following code: |
| 85 | + |
| 86 | +```sh |
| 87 | +poetry run pytest --cov-report term-missing --cov=plotly-resampler tests |
| 88 | +``` |
| 89 | + |
| 90 | +To get the selenium tests working you should have Google Chrome installed. |
| 91 | + |
| 92 | +If you want to visually follow the selenium tests; |
| 93 | +* change the `TESTING_LOCAL` variable in [tests/conftest.py](tests/conftest.py) to `True` |
| 94 | + |
| 95 | +### Generating the docs |
| 96 | + |
| 97 | +When you've added or updated a feature; it is always a good practice to alter the |
| 98 | +documentation and [changelog.md](CHANGELOG.md). |
| 99 | + |
| 100 | +The current listing below gives you the provided steps to regenerate the documentation. |
| 101 | + |
| 102 | +1. Make sure that your python env is active (e.g., by running `poetry shell`) |
| 103 | +2. Navigate to `sphinx/docs` and run from that directory: |
| 104 | +```bash |
| 105 | +sphinx-autogen -o _autosummary && make clean html |
| 106 | +``` |
| 107 | + |
| 108 | +## More details on Pull requests |
| 109 | + |
| 110 | +The preferred workflow for contributing to plotly-resampler is to fork the |
| 111 | +[main repository](https://github.com/predict-idlab/plotly-resampler) on |
| 112 | +GitHub, clone, and develop on a branch. Steps: |
| 113 | + |
| 114 | +1. Fork the [project repository](https://github.com/predict-idlab/plotly-resampler) |
| 115 | + by clicking on the 'Fork' button near the top right of the page. This creates |
| 116 | + a copy of the code under your GitHub user account. For more details on |
| 117 | + how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/). |
| 118 | + |
| 119 | +2. Clone your fork of the plotly-resampler repo from your GitHub account to your local disk: |
| 120 | + |
| 121 | + ```bash |
| 122 | + $ git clone [email protected]:YourLogin/plotly-resampler.git |
| 123 | + $ cd plotly-resampler |
| 124 | + ``` |
| 125 | + |
| 126 | +3. Create a ``feature`` branch to hold your development changes: |
| 127 | + |
| 128 | + ```bash |
| 129 | + $ git checkout -b my-feature |
| 130 | + ``` |
| 131 | + |
| 132 | + Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch! |
| 133 | + |
| 134 | +4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files: |
| 135 | + |
| 136 | + ```bash |
| 137 | + $ git add modified_files |
| 138 | + $ git commit |
| 139 | + ``` |
| 140 | + |
| 141 | + to record your changes in Git, then push the changes to your GitHub account with: |
| 142 | + |
| 143 | + ```bash |
| 144 | + $ git push -u origin my-feature |
| 145 | + ``` |
| 146 | + |
| 147 | +5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork) |
| 148 | +to create a pull request from your fork. This will send an email to the committers. |
| 149 | + |
| 150 | +(If any of the above seems like magic to you, please look up the |
| 151 | +[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.) |
| 152 | + |
| 153 | +### Pull Request Checklist |
| 154 | + |
| 155 | +We recommended that your contribution complies with the |
| 156 | +following rules before you submit a pull request: |
| 157 | + |
| 158 | +- Follow the PEP8 Guidelines. |
| 159 | + |
| 160 | +- If your pull request addresses an issue, please use the pull request title |
| 161 | + to describe the issue and mention the issue number in the pull request description. |
| 162 | + This will make sure a link back to the original issue is created. |
| 163 | + |
| 164 | +- All public methods should have informative *numpy* docstrings with sample |
| 165 | + usage presented as doctests when appropriate. Validate whether the generated |
| 166 | + documentation is properly formatted (see below). |
| 167 | + |
| 168 | +- Please prefix the title of your pull request with `[MRG]` (Ready for |
| 169 | + Merge), if the contribution is complete and ready for a detailed review. |
| 170 | + An incomplete contribution -- where you expect to do more work before |
| 171 | + receiving a full review -- should be prefixed `[WIP]` (to indicate a work |
| 172 | + in progress) and changed to `[MRG]` when it matures. WIPs may be useful |
| 173 | + to: indicate you are working on something to avoid duplicated work, |
| 174 | + request broad review of functionality or API, or seek collaborators. |
| 175 | + WIPs often benefit from the inclusion of a |
| 176 | + [task list](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments) |
| 177 | + in the PR description. |
| 178 | + |
| 179 | +- When adding additional functionality, provide at least one |
| 180 | + example notebook in the ``plotly-resampler/examples/`` folder or add the functionality in an |
| 181 | + existing notebook. Have a look at other examples for reference. |
| 182 | + Examples should demonstrate why the new functionality is useful in practice and, |
| 183 | + if possible, benchmark/integrate with other packages. |
| 184 | + |
| 185 | +- Documentation and high-coverage tests are necessary for enhancements to be |
| 186 | + accepted. Bug-fixes or new features should be provided with |
| 187 | + [non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing). |
| 188 | + These tests verify the correct behavior of the fix or feature. In this |
| 189 | + manner, further modifications on the code base are granted to be consistent |
| 190 | + with the desired behavior. |
| 191 | + For the Bug-fixes case, at the time of the PR, this tests should fail for |
| 192 | + the code base in master and pass for the PR code. |
| 193 | + |
| 194 | + |
| 195 | +--- |
| 196 | + |
| 197 | +Bonus points for contributions that include a performance analysis with a benchmark script and profiling output (please report on the GitHub issue). |
| 198 | + |
0 commit comments