So you’re thinking about contributing to VisPy…great! Below you’ll find instructions on the different ways to contribute and how to do it. You’ll also find information about coding style and other best practices.
VisPy accepts contributions from anyone as long as they meet our standards. While we will accept contributions from anyone, we especially value ideas and contributions from folks with diverse backgrounds and identities. There are many ways to contribute (see below) and no contribution is too small.
Bugs: Tell us when you think you’ve found something wrong or when you just can’t get something to work after following the instructions.
Features: Have an idea how VisPy could be improved? We’d like to hear it. Bonus points if you have ideas on how it can be implemented.
Ticket Review: Not sure how to help out, but you’ve become pretty familiar with the project? Help the VisPy maintainers clean out old, duplicate, or already resolved bug reports and feature requests.
Documentation: See a typo? Please correct us. Is something documented wrong or out of date? Tell us about it. Could the documentation be made less confusing if their was more detail? Let us know. Tell us what was confusing. Even better, tell us what would have made it easier to understand in the first place. See below for more info on best practices.
Code: If there is a bug that you want to fix or a feature you want to add, please let us know. See below for how we prefer you make these contributions.
Almost all communication with the VisPy maintainers should be done through the main VisPy GitHub repository: https://github.com/vispy/vispy/
Bug reports and feature requests can be submitted through the “Issues” on the repository. This GitHub page can help you create an issue if you’re unfamiliar with the process. When you create an issue you’ll see VisPy’s template asking you for specific information. It is really important that you provide as much of this information as possible. Most importantly for bugs is providing a Minimal Complete and Verifiable Example (MCVE)
Any changes to actual code, including documentation, should be submitted as a pull request on GitHub. GitHub’s documentation includes instructions on making a pull request if you’re new to GitHub or to git in general. Please make sure to submit pull requests using a new branch (not your fork’s master branch). Don’t be afraid to submit a pull request with only partial fixes/features. Pull requests can always be updated after they are created. Creating them early gives maintainers a chance to provide an early review of your code if that’s something you’re looking for. See below for more information on writing documentation and checking your changes.
No matter how you contribute, VisPy maintainers will try their best to read, research, and respond to your query as soon as possible. For code changes, automated checks and tests will run on GitHub to provide an initial “review” of your changes.
The best way to ask for help from VisPy maintainers is to talk to us on gitter. If you have more general VisPy questions that users may be able to help with check out the main gitter channel. If you have questions specific to VisPy’s design or how you should contribute to VisPy there is a gitter channel specifically for VisPy Developers. Lastly, feel free to create an issue on GitHub to ask a question. If you’ve already created a pull request you can comment there.
In general, VisPy follows the PEP 8 style guidelines:
https://www.python.org/dev/peps/pep-0008/
The easiest way to see if your meeting these guidelines is to code as you normally would and run flake8 to check for errors (see below). Otherwise, see existing VisPy code for examples of what we expect.
flake8
Code style is automatically checked by VisPy’s Continuous Integration (CI). If you’d like to check the style on your own local machine you can install and run the flake8 utility from the root of the vispy repository. To install:
pip install flake8
Then run the following from the root of the VisPy directory:
python make test flake
This will inform you of any code style issues in the entire vispy python package directory.
All docstrings in VisPy’s python code follow the NumPy style. You can find the full reference here:
https://numpydoc.readthedocs.io/en/latest/format.html
However, the simplest way to get a hang of this style is to look at the existing VisPy code.
Similar to code style, documentation style is tested during VisPy’s automated testing when you create or edit a pull request. If you’d like to check it locally you can use the same flake8 tool as for code, but with the addition of the flake8-docstring package. To install:
flake8-docstring
pip install flake8-docstrings
This will check both code style and docstring style.
VisPy depends on self-contained tests to know that changes haven’t broken any existing functionality. Our unit tests are written using the pytest library. Some parts of VisPy require extra steps to test them thoroughly, but utilities exist to help with this. For example, VisPy has multiple backends that can be used, so to be thoroughly checked tests should be run for each of these backends. Luckily, VisPy’s automated tests will run every test over a series of backends for you when you make a pull request so you shouldn’t normally have to worry about this in your local testing.
pytest
As mentioned, tests are written so that they can be run with pytest. In the most basic cases this means adding one or more functions or classes to modules in a tests directory. For example, tests for the vispy.plot subpackage are in the vispy/plot/tests/test_plot.py module. Note that both the module and the function should start with test_ so that pytest can discover them.
tests
vispy/plot/tests/test_plot.py
test_
Tests should completely test the changes being submitted. Depending on the changes this may be as simple as calling the function or as complicated as building a full visualization with a Canvas and set of Visual objects. Looking at existing tests is a good place to start. If you have any questions you can always contact the VisPy maintainers or leave a comment on your pull request asking for assistance.
For more complex tests, you may require that certain dependencies be installed or that a GUI window can be opened. In those case you can look at the various decorators in vispy.testing. For example, if you need to make a Canvas, your test should only run when a VisPy Application can be created. In this case the requires_application() decorator can be used:
vispy.testing
requires_application()
from vispy.testing import requires_application @requires_application() def test_my_change(): with app.Canvas() as c: # do something with the Canvas 'c'
All available decorators in the testing module start with requires_. See the module documentation for more information.
requires_
In the basic cases, the traditional method of calling pytest <module.py> will work to run a limited set of tests:
pytest <module.py>
pytest vispy/plot/tests/test_plot.py
However, this will only run on one backend. To easily run tests on multiple backends:
python make test unit
This runs tests in the same way that tests are run on the CI environments. Additional test commands are available including:
python make test nobackend
To run tests without any backend selected. Or:
python make test full
To run both nobackend and unit tests as well as “extra” tests including docstring and flake tests. Lastly:
python make test examples
Which will attempt to run all example scripts.
Note
Due to environment, GPU driver, or dependency differences not all tests may pass on your system. The CI environments should be considered the “one truth” for passing tests until tests are made more flexible for differences in systems.
Any contributors wishing to modify the Sphinx Documentation from the VisPy repository’s “doc” directory or the Jupyter Widget in the “js” directory should note that these directories are actually special “git submodules”. Git submodules are special directories in a git repository that point to external git repositories. In the case of “doc”, this points to:
https://github.com/vispy/vispy-website
In the case of “js”, this points to:
https://github.com/vispy/vispy.js/
Any modifications that you wish to make to either of these directories MUST be submitted to their respective repositories first. After they are merged in those repositories then you or the VisPy maintainers can update the git submodules in the main VisPy repository to point to these new versions. Of course, if you have any questions, feel free to ask the VisPy maintainers.