pyqtgraph/CONTRIBUTING.md

73 lines
3.2 KiB
Markdown

# Contributing to PyQtGraph
Contributions to pyqtgraph are welcome!
Please use the following guidelines when preparing changes:
## Submitting Code Changes
* The preferred method for submitting changes is by github pull request against the "develop" branch.
* Pull requests should include only a focused and related set of changes. Mixed features and unrelated changes may be rejected.
* For major changes, it is recommended to discuss your plans on the mailing list or in a github issue before putting in too much effort.
* Along these lines, please note that `pyqtgraph.opengl` will be deprecated soon and replaced with VisPy.
## Documentation
* Writing proper documentation and unit tests is highly encouraged. PyQtGraph uses nose / pytest style testing, so tests should usually be included in a tests/ directory adjacent to the relevant code.
* Documentation is generated with sphinx; please check that docstring changes compile correctly
## Style guidelines
* PyQtGraph prefers PEP8 for most style issues, but this is not enforced rigorously as long as the code is clean and readable.
* Use `python setup.py style` to see whether your code follows the mandatory style guidelines checked by flake8.
* Exception 1: All variable names should use camelCase rather than underscore_separation. This is done for consistency with Qt
* Exception 2: Function docstrings use ReStructuredText tables for describing arguments:
```text
============== ========================================================
**Arguments:**
argName1 (type) Description of argument
argName2 (type) Description of argument. Longer descriptions must
be wrapped within the column guidelines defined by the
"====" header and footer.
============== ========================================================
```
QObject subclasses that implement new signals should also describe
these in a similar table.
## Testing Setting up a test environment
### Dependencies
* tox
* tox-conda
* pytest
* pytest-cov
* pytest-xdist
* Optional: pytest-xvfb
If you have pytest < 5, you may also want to install the pytest-faulthandler
plugin to output extra debugging information in case of test failures. This
isn't necessary with pytest 5+ as the plugin was merged into core pytest.
### Tox
As PyQtGraph supports a wide array of Qt-bindings, and python versions, we make use of `tox` to test against most of the configurations in our test matrix. As some of the qt-bindings are only installable via `conda`, `conda` needs to be in your `PATH`, and we utilize the `tox-conda` plugin.
* Tests for a module should ideally cover all code in that module, i.e., statement coverage should be at 100%.
* To measure the test coverage, un `pytest --cov -n 4` to run the test suite with coverage on 4 cores.
### Continous Integration
For our Continuous Integration, we utilize Azure Pipelines. On each OS, we test the following 6 configurations
* Python2.7 with PyQt4
* Python2.7 with PySide
* Python3.6 with PyQt5-5.9
* Python3.6 with PySide2-5.9
* Python3.7 with PyQt5-5.12
* Python3.7 with PySide2-5.12
More information on coverage and test failures can be found on the respective tabs of the [build results page](https://dev.azure.com/pyqtgraph/pyqtgraph/_build?definitionId=1)