73 lines
3.2 KiB
Markdown
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)
|