External file format readers
============================

File format readers recognized by Bio-Formats can be defined as either "core" or "external".
A core reader is maintained by the OME team, and included in either the `formats-bsd` or `formats-gpl`
component in the `ome/bioformats` repository on GitHub. An external reader is not included in the
`ome/bioformats` repository, and in most cases is not maintained by the OME team. [1]_

Bio-Formats contains a file named :source:`readers.txt <components/formats-api/src/loci/formats/readers.txt>`
which records every recognized reader class name. This file is used by the main reader class
(:javadoc:`loci.formats.ImageReader <loci/formats/ImageReader.html>`) to find installed readers.

For readers that are included in core Bio-Formats (i.e. the `ome/bioformats` repository on GitHub),
a line containing just the fully qualified class name is added, e.g.:

.. code-block::

  loci.formats.in.OMETiffReader         # tif

An optional comment can be added after the class name using `#`.

Readers that are not in `ome/bioformats` and which are not included in Bio-Formats releases can be
defined as "external" readers, e.g.:

.. code-block::

  loci.formats.in.ZarrReader[type=external]         # .zarr

This allows Bio-Formats to attempt to load a reader that was installed separately,
but quietly ignore if it is not found.

.. _external-reader-criteria:

When to use an external reader
------------------------------

The OME team often encourages new readers to be proposed as "external" under any of the following conditions:

- the newly introduced reader code is very large and/or complex
- native libraries or closed-source dependencies are required
- a public format specification document or reference implementation is not available
- the reader covers an imaging domain which is unfamiliar to the OME team
- test data cannot be provided to the OME team
- the reader needs to be updated outside of the normal Bio-Formats release process
- the reader code does not comply with `OME code contribution policies <https://ome-contributing.readthedocs.io/en/latest/code-contributions.html>`_
- developers/maintainers of the reader are not able to address feedback provided by the OME team during `code review and testing <https://ome-contributing.readthedocs.io/en/latest/code-contributions.html#procedure-for-accepting-code-contributions>`_

When considering a new reader, we suggest discussing with the OME team first before making substantial development.
The OME team is responsible for making the final determination of whether a new reader should be defined as external.

How to propose an external reader
---------------------------------

As indicated above, we suggest discussing with the OME team before investing significant time in a new reader.

At minimum, open a new pull request or issue on `ome/bioformats` that proposes to update `readers.txt` as indicated above,
including the following information:

- where to find the reader source code
- who is maintaining the external reader, and an acknowledgement that the OME team is not responsible for maintaining this reader
- where/how the reader will be released
- test data, if possible
- supporting documentation (issues, forum threads, etc.) indicating why this reader is necessary

We strongly prefer to be able to test a proposed external reader before approving it, but recognize this may
not always be possible. In these cases, we may ask for additional information in place of our own testing.

.. seealso::

  `OME's Third Party Contribution and Interaction Policy <https://ome-contributing.readthedocs.io/en/latest/third-party-policy.html>`_

What external reader ownership involves
---------------------------------------

Developing an external reader means taking complete ownership and responsibility for
the development, maintenance, testing, and distribution of the reader and its dependencies.
The OME team will not review code, fix issues, or otherwise participate in the development or
release process. As a result, it is very important to have a maintenance and testing
plan that includes:

- where issues should be reported
- who is responsible for fixing issues and releasing new versions
- where/how to find new versions of the reader, e.g. a Fiji update site

We strongly encourage reader maintainers to follow a support pattern similar to that used for
core Bio-Formats, which includes:

- publicly accessible issue tracking
- participation in discussions on `forum.image.sc <https://forum.image.sc/>`_
- public roadmaps and release announcements

Recategorizing an existing reader
---------------------------------

If the OME team determines that an existing core reader meets the external reader
criteria in :ref:`external-reader-criteria`, and a suitable maintainer can be identified,
then we may propose to recategorize the reader as external. This is our preferred alternative
to removing it from both core Bio-Formats and :source:`readers.txt <components/formats-api/src/loci/formats/readers.txt>`.

In the event that recategorizing is necessary, we will make contact with the proposed
maintainer to discuss next steps.

.. [1] A notable exception is `ZarrReader <https://github.com/ome/ZarrReader>`_, which is an external
       reader maintained by the OME team. This reader is externalized primarily to allow for updates
       outside of the normal Bio-Formats release process. See further discussion in
       `this issue <https://github.com/ome/ZarrReader/issues/32>`_.
