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.
Who can contribute?¶
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.
What can be contributed?¶
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.
How can I contribute?¶
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 main 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.
What if I need help?¶
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.
See the installation instructions for different ways to install VisPy and its dependencies. We suggest installing VisPy from source if you are planning on modifying any code.
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.
Checking Code Style¶
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 package directory.
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.
Checking Documentation Style¶
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
Then run the following from the root of the VisPy directory:
python make test flake
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
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
tests directory. For example, tests for the vispy.plot subpackage are
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
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
requires_application() decorator can be
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
the module documentation for more information.
In the basic cases, the traditional method of calling
will work to run a limited set of tests:
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.
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.
Sphinx Documentation and Jupyter Widget¶
VisPy’s documentation website is a Sphinx project stored in the “doc” directory of the repository. To generate the documentation run:
cd doc make html
Repeated execution of
make html will reuse information from previous runs
which may be faster, but may also produce incorrect output in specific cases.
To make sure, you can clean out the build directory by running
To view the output you can view the build folder in a browser:
As part of the documentation generation, the sphinx-gallery project will run all of the examples to generate screenshots for the gallery pages. This can take a long time and is unnecessary if you aren’t modifying the gallery or examples. To build the site without generating the gallery run:
make html SPHINXOPTS="-D plot_gallery=0"
VisPy no longer has a jupyter widget as part of the main VisPy Python package. Instead the “jupyter_rfb” package is used through the “jupyter_rfb” backend of VisPy. Major changes to this backend will likely need changes to the jupyter_rfb library which can be found here:
Updating my fork’s branch to “main”¶
The VisPy project has switched to using the branch name “main” as its primary
branch. If you forked the repository before this change, you may find it
confusing to work between your fork and the upstream VisPy repository.
If you wish to update your fork, go to the branches page for your repository
https://github.com/<yourusername>/vispy/branches) and edit/rename
the “master” branch to “main”.
On your local system, you’ll also want to point to the new name as well. GitHub provides instructions for doing this update. For convenience they’ve been copied below:
git branch -m master main git fetch origin git branch -u origin/main main git remote set-head origin -a
If you’ve configured multiple “remotes” on your system, you may need to change these commands with the proper remote name.