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
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
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
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:
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.
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
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
All docstrings in VisPy’s python code follow the NumPy style. You can find
the full reference here:
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:
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.
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 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
from vispy.testing import requires_application
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.
In the basic cases, the traditional method of calling pytest <module.py>
will work to run a limited set of tests:
However, this will only run on one backend. To easily run tests on multiple
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.
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:
In the case of “js”, this points to:
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