============
Contributing
============


.. toctree::
    :hidden:
    :maxdepth: 2
  
    Writing v2 Plugins <plugins>


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 <https://github.com/imageio/imageio>`_ 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 <https://github.com/imageio/imageio>`_ 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**

.. autosummary::

    imageio.plugins

**v3 plugin docs**

.. autosummary::
    :template: better_class.rst
    :toctree: ../_autosummary

    imageio.core.v3_plugin_api.PluginV3
    imageio.core.v3_plugin_api.ImageProperties

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**

.. code-block::

    # 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**

.. code-block::

    # 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 <https://github.com/imageio/imageio>`_ 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](https://github.com/imageio/imageio/blob/master/imageio/config/extensions.py)
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