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:

  1. Navigate to the page you wish to improve.

  2. Click on the “Edit this Page” button on the right side panel.

  3. Make your changes to the file that opens.

  4. At the bottom of the page under “Commit Changes” choose a descriptive commit message (e.g., “fixed typo in examples”).

  5. Click the button “Propose Changes”.

  6. 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 def 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

imageio.plugins

Here you can find documentation on how to write your own plugin to allow ImageIO to access a new backend.

v3 plugin docs

imageio.core.v3_plugin_api.PluginV3(request)

A ImageIO Plugin.

imageio.core.v3_plugin_api.ImageProperties(...)

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:

  1. Register the plugin as a known_plugin

  2. 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 readiing 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