Contributing#
Becoming a contributor can take as little as 2 minutes (e.g., via a small doc PR) and doesn’t require vast coding experience. We are open for contributions in many ways and, if you would like to get involved but aren’t sure where to start, create a new issue and we will help you get started. In particular, we are also extremely happy for any help with
bugfixes,
improving our documentation,
improving our DevOp pipeline,
improving the design of our website,
new backends/plugins,
and new features.
Check the relevant section below for a guide on how to get started in any of these areas.
Small Changes to the Documentation#
Note
A small documentation pull request includes changes that only affect a single file. Examples include fixing typos or broken links, rewriting a paragraph for clarity, or adding examples.
A small doc PR is very quick and doesn’t require any local setup on your end. All you need is a GitHub account. Here are the steps involved:
Navigate to the page you wish to improve.
Click on the “Edit this Page” button on the right side panel.
Make your changes to the file that opens.
At the bottom of the page under “Commit Changes” choose a descriptive commit message (e.g., “fixed typo in examples”).
Click the button “Propose Changes”.
That’s it. The ImageIO team thanks you for your contribution!
Large Changes to the Documentation#
Installation
For large changes to the documentation, you will have to set up a local development environment with the documentation dependencies installed:
# 1. Fork the ImageIO repository
# 2. If you want to use a virtual environment for your setup, create and activate it now.
git clone https://github.com/<replace_by_your_username>/imageio.git
cd imageio
pip install -e .[doc]
# create and checkout a new branch for your contribution
# Note: replace <branch_name> with a descriptive, but short, name
git checkout -b <branch_name>
git push --set-upstream origin <branch_name>
# building the docs locally on Linux or MacOS
# Note: to rebuild the docs, execute this line again
sphinx-build ./docs ./build
# building the docs locally on Windows
# Note: to rebuild the docs, execute this line again
sphinx-build .\docs .\build
Developing the PR
Next, you will have to add your modifications to the docs; remember to commit frequently. You are welcome to reach out during this process if you want feedback or have any doubts. Further, you may wish to create a draft PR with your changes, so that we can discuss more easily.
We use sphinx to generate the website and the API has narrative docs.
Documentation of the actual functions is autogenerated using numpydoc, and is
linked to from the narrative API docs. Further, the list of supported formats,
too, is autogenerated using a custom sphinx extension (imageio_ext.py
);
essentially, it parses the respective format RST files using jinja and inserts
the formats from imageio.config.known_extensions
.
Submitting the PR
Once you are happy with your changes, push your changes to your local fork, head over to the main repo and create a new PR. In the description, briefly summarize what the changes are about (there is no fixed format). If we discussed them before in an issue, add a reference to that issue, so that we can track it. From there, we will help you by reviewing your changes, discussing any changes and eventually merging your work into ImageIO.
Thank you for contributing!
Fixing a Bug#
Note
We currently don’t have a dedicated maintainer that uses MacOS as their primary development platform. If you would like to suggest yourself, please get in touch, e.g., via a new issue.
The first step to fixing a bug is to open a new issue that describes the bug (ideally including a [mwe](https://en.wikipedia.org/wiki/Minimal_working_example)) to discuss where the fix should live. Alternatively, if an issue already exists, leave a comment to let us know you want to work on it.
In general, a bugfix follows the usual open-source routine. Here is a rough outline:
# Fork the ImageIO repository
git clone https://github.com/<replace_by_fork_location>/imageio.git
cd imageio
# Note: replace <plugin_name> with the plugin that has the bug to
# install optional dependencies
pip install -e .[dev,<plugin_name>]
# Note: replace <branch_name> with a descriptive, but short, name
git checkout -b <branch_name>
git push --set-upstream origin <branch_name>
pytest # run the existing test suite to verify install
# Add a unit test that reproduces the faulty behavior
# Apply the changes to fix the bug. Remember to commit frequently.
# check if your changes are covered by tests
coverage run -m pytest
coverage report -m
# If changes are not fully covered, add test(s) to cover the
# missing branches.
# Submit a PR. In the description, reference the abovementioned
# issue and give a brief description of the changes.
Thank you for contributing!
Adding a new Feature#
Note
We currently don’t have a dedicated maintainer that uses MacOS as their primary development platform. If you would like to suggest yourself, please get in touch, e.g., via a new issue.
The first step to contributing a new feature is to open a new issue on our issue page so we can discuss how the feature should look like, if it can work with the relevant backends, and fits within the scope of the library.
Once that is out of the way, the procedure usually follows the following steps:
# Fork the ImageIO repository
git clone https://github.com/<replace_by_fork_location>/imageio.git
cd imageio
# Note: replace <plugin_name> with the plugin that has the bug to
# install optional dependencies
pip install -e .[dev,<plugin_name>]
# Note: replace <branch_name> with a descriptive, but short, name
git checkout -b <branch_name>
git push --set-upstream origin <branch_name>
pytest # run the existing test suite to verify install
# Add the desired/discussed functionality
# For each new function you've created add a descriptive docstring
# compliant with numpydoc
# Add an example to ``docs/examples.rst`` showing off the new
# feature
# Add unit tests to verify that the feature does what it is
# intended to do
# check if your changes are covered by tests
coverage run -m pytest
coverage report -m
# If changes are not fully covered, add test(s) to cover the
# missing branches.
# Submit a PR. In the description, reference the feature issue and
# give a brief description of the changes.
Thank you for contributing!
Webdesign#
Warning
We currently don’t have a dedicated maintainer for this area. If you would like to suggest yourself, please get in touch, e.g., via a new issue.
There is currently no established way of suggestion webdesign related changes. If you have any suggestions regarding
the structure/layout of the docs
improvements of the template or its config
styling of the website
(other webdesign related items)
Please open a new issue and we will discuss with you.
DevOps#
Before you go and improve our tooling, please start by first opening a new issue and discussing your idea with us. We ask this, because we want to make sure that there is at least one maintainer familiar with the technology you want to use. If anything breaks in the CI/CD pipeline, it will have a direct impact on our release cycle, and we would like to make sure that at least one maintainer is able to step in and fix it in a timely fashion.
Installation
While you may be able to complete some devops related contributions in GitHub itself, a local setup will perform better in most situations:
# 1. Fork the ImageIO repository
git clone https://github.com/<replace_by_your_username>/imageio.git
cd imageio
pip install -e .
# create and checkout a new branch for your contribution
# Note: replace <branch_name> with a descriptive, but short, name
git checkout -b <branch_name>
git push --set-upstream origin <branch_name>
Developing the PR
Do your changes, and remember to commit frequently. If you want to test your
changes against our CI/CD provider (GH Actions), you can submit a draft PR,
which we will review and run. Alternatively, you configure your local fork to
execute actions and develop against it. You can find our workflows in the
.github
folder.
Continuous Integration (CI): The core of our CI is a matrix test across all
major OSes and supported python versions running a testsuite based on
pytest
. Additionally, we track linting errors (black + flake8), coverage
(codecov), and have readthedocs build a preview of the documentation.
Continuous Deployment (CD): Our continuous deployment pipeline checks weekly (Monday night, EU time) for any changes to the repository. If there are any, it uses python-semantic-release to figure out if the version should bump and a new release should be made. If so, all tests are run against the master branch, the version is bumped, and a new release is made and published to GitHub and PyPI. Further, we have a feedstock on conda-forge which manages releases to conda.
Submitting the PR
Once you are happy with your changes, push your changes to your local fork, head over to the main repo and create a new PR. In the description, briefly summarize what the changes are about (there is no fixed format) and add a reference to the issue in which we discussed them. From there, we will help you by reviewing your changes, discussing them and eventually merging your work into ImageIO.
Thank you for contributing!
Implementing a new Plugin#
Plugins allow integration of a new backends into ImageIO. They can exist independently of ImageIO; however, we encourage you to contribute any plugins back upstream. This way others, too, can benefit from using the new backend and you will get compatibility guarantees by virtue of the backend becoming part of our test suite.
Note
These instructions assume that you indeed wish to contribute the plugin.
If you don’t, then you won’t need a dev installation of ImageIO and can write the plugin directly. In this case, you will have to pass the plugin class to API calls using the plugin kwarg. For example:
import imageio as iio
from my_plugin import PluginClass
iio.imread(ImageResource, plugin=PluginClass)
Installation
To develop a new plugin, you can start off with a simple dev install:
# 1. Fork the ImageIO repository
git clone https://github.com/<replace_by_your_username>/imageio.git
cd imageio
pip install -e .[dev]
# create and checkout a new branch for your contribution
# Note: replace <branch_name> with a descriptive, but short, name
git checkout -b <branch_name>
git push --set-upstream origin <branch_name>
# verify installation
pytest
Develop the Plugin
To write a new plugin, you have to create a new class that follows our plugin API, which is documented below:
v2 plugin docs
Here you can find documentation on how to write your own plugin to allow ImageIO to access a new backend. |
v3 plugin docs
|
A ImageIO Plugin. |
Standardized Metadata |
The file itself should be placed into our plugins folder at
imageio\plugins\your_plugin.py
.
Declare Dependencies
Plugins typically have at least one external dependency: the backend they use to
do the decoding/encoding. This dependency (and any others a plugin may have)
have to be declared in our setup.py
.
All plugins start out as optional dependencies (but may be promoted if they turn out stable and useful ;) ). As such, to declare dependencies of a plugin add an item to the extra_requires dict. The key name typically matches the name of the backend, and the value is a list of dependencies:
extras_require = {
# ...
"my_backend": ["my_backend", ...],
}
That said, a plugin can assume that its dependencies are installed, i.e., it doesn’t have to explicitly assert that imports resolve. We catch any ImportError internally and use it to inform the user that they have to install missing dependencies via:
pip install imageio[my_backend]
Register the Plugin
Registering the plugin with ImageIO enables various kinds of auto-magic. Currently this involves two steps:
Register the plugin as a known_plugin
Associate supported extensions with the plugin
First, add the plugin to the list of known plugins. This allows ImageIO to try
the plugin in case no better suited one can be found and also enables all other
optimizations. For this, add a new item to the dict in
imageio.config.plugins.py
. The key is the name under which the plugin will
be known (usually the name of the backend) and the value is an instance of
PluginConfig
, for example:
known_plugins["my_plugin"] = PluginConfig(
name="my_plugin", # (same as key)
class_name="MyPluginClass", # the name of the class
module_name="imageio.plugins.my_plugin" # where the class is implemented
is_legacy: bool = True, # True if plugin follows V2 API
install_name: str = "my_backend", # name of the optional dependency
)
For more details on the PluginConfig class, check the classes docstring.
Second, if the plugin adds support for any new formats that were not previously
supported by ImageIO, declare those formats in imageio.config.extensions.py
.
For this, add items to the extension_list
; items are instances of the
FileExtension
class:
FileExtension(
name="Full Name of Format",
extension=".file_extension", # e.g. ".png"
priority=["my_plugin"], # a list of plugins that supports reading this format
),
Plugins listed in priority
are assumed to be able to read the declared
format. Further, ImageIO will prefer plugins that appear earlier over plugins
that appear later in the list, i.e., they are tried first.
Finally, for each format that is already supported by other plugins, add the new plugin
at the end of the priority
list. (This avoids breaking existing downstream code.)
Document the Plugin
# build the docs
sphinx-build ./docs ./build # MacOS / Linux
sphinx-build .\docs .\build # Windows
Beyond the plugin itself, you will have to write documentation for it that tells others what features are available and how to use it. In ImageIO classes are documented using numpydoc, so they should follow numpy’s documentation style. Most importantly, you will have to add a module docstring to the plugin file (check the other plugins for examples), which will be used as the entrypoint for your plugin’s documentation.
Once you have written something, hook the documentation into our docs. For this
add it’s import path (imageio.plugins.your_module_name) in
docs\reference\index.rst
. It should be inside the autosummary block that
lists all plugins.
Test the Plugin
# run tests
pytest # run all
pytest path/to/test/file.py # run specific module
pytest path/to/test/file.py::test_name_of_test # run specific test
# check coverage
coverage run -m pytest # update the coverage logs
coverage report -m # report coverage in shell
To test your plugin, create a new test file at tests\test_myplugin.py
. In
the file, define functions that have their name begin with test_
(example:
def test_png_reading():
) and fill them with code that uses your plugin.
Our main requirement for tests of new plugins is that they cover the full plugin. Ideally, they also test reading and writing of all supported formats, but this is not strictly necessary. Check the commands above for how to run tests and check test coverage of your plugin.
Submitting the PR
Once you are happy with the plugin, push your changes to your local fork, head over to the main repo and create a new PR. In the description, briefly summarize what the plugin does (there is no fixed format) and, if it exists, add a reference to the issue in which the plugin is discussed. From there, we will help you by reviewing your changes, discussing them and eventually merging your plugin into ImageIO.
Thank you for contributing!
Adding a missing Format#
Adding a new format (or updating an existing one) can be done directly in
GitHub. Navigate to [this
page](imageio/imageio)
and click on the “edit this file” button (looks like a pen). From here,
either edit the existing format, e.g., by adding a new backend that supports it in priority
,
or by add a new format. For this add this snippet to the bottom of the extension_list
:
FileExtension(
name="<Full Name of File Format>", # e.g., Hasselblad raw
extension="<extension>", # e.g., .3fr
priority=<list of supporting backend names>, # e.g., ["RAW-FI"]
)
Thank you for contributing!
Full Developer Setup#
Note
This section is intended for library maintainers and people that plan to make multiple contributions of various kinds.
If you plan to make a series of contributions, we recommend a development installation with all plugins:
# 1. Fork the ImageIO repository
# 2. Optional: Create and activate your virtual environment of choice
# install
git clone https://github.com/<replace_by_fork_location>/imageio.git
cd imageio
pip install -e .[full]
# download test images and run all tests
pytest
# build the docs
sphinx-build ./docs ./build # MacOS / Linux
sphinx-build .\docs .\build # Windows
# check coverage
coverage run -m pytest # update the coverage logs
coverage report -m # report coverage in shell