-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Migrate process content from ome#132
- Loading branch information
Showing
1 changed file
with
137 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,138 @@ | ||
| RFC-0 | ||
| ===== | ||
| # RFC-0 | ||
|
|
||
| Example | ||
| Original NGFF consensus process | ||
|
|
||
| ## Status | ||
|
|
||
| This is a historical RFC, drafted after the fact, and has | ||
| been outdated by [RFC-1](../1/). | ||
|
|
||
| | Name | GitHub Handle | Institution | Date | Status | | ||
| |------------|---------------|-------------------|------------|--------| | ||
| | Josh Moore | joshmoore | German BioImaging | 2024-02-07 | Author | | ||
|
|
||
| ## Overview | ||
|
|
||
| Versions of the NGFF specification up to and including v0.4 followed a | ||
| consensus model of decision making. This is being recorded as RFC-0 | ||
| in order to allow other historical RFCs, as listed in [RFC-1](../1/), | ||
| to reference the process under which they were discussed. | ||
|
|
||
| ## Background | ||
|
|
||
| NGFF development began as a relatively focused group of individuals writing | ||
| specifications. At the time, this group was called "editors". This document | ||
| describes the process that was used for reviewing and finding a consensus on | ||
| their work before [RFC-1](../1/) was adopted. This period started with the | ||
| first commit 2020-11-17 and covers versions 0.1 through 0.5, even though | ||
| version 0.5 was developed concurrently with [RFC-1](../1/). | ||
|
|
||
| ## Proposal | ||
|
|
||
| A general outline of how versions were decided: | ||
|
|
||
| * **Proposals** generally started with fairly strong support during **community | ||
| calls** which often led to the drafting of an issue. In the case of v0.1, | ||
| the first issue was on the zarr-specs repository, | ||
| <https://github.com/zarr-developers/zarr-specs/issues/50>. | ||
| * To the extent possible, **implementations** were started as soon as there was | ||
| a general consensus since it is much easier to show what is intended when | ||
| there is draft data which requires a writer implementation. This data was | ||
| often uploaded to a temporary S3 location. | ||
| * Once the **PR was opened**, there was a general call for **feedback** | ||
| typically via the <https://image.sc> **ngff group** with various iterations. | ||
| Sometimes a second **community call** occurred at this point. | ||
| * Once no further changes were requested, a final call with a deadline for | ||
| release was made either via the image.sc group or a community call or both. | ||
| * The tag was pushed and then an attempt to make sure all implementations were | ||
| aligned followed. | ||
|
|
||
| An exception to the above were a small number of "transitional" specifications. | ||
| This includes the `omero` and `bioformats2raw.layout` sections. They differ | ||
| from other proposals in that: | ||
|
|
||
| - They are attempting to capture a format that has been produced for some time. | ||
| - They affect one or more _existing_ versions. | ||
| - Support in all clients seems to be less essential, though just how to | ||
| quantify this should be part of this definition. | ||
|
|
||
| ## Requirements | ||
|
|
||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", | ||
| "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be | ||
| interpreted as described in IETF RFC 2119. | ||
|
|
||
| ## Stakeholders | ||
|
|
||
| * **editors**: those who have authored or are authoring specifications. Note: this terminology | ||
| differs from that in [RFC-1](../1/) and the website and specifications have been updated to reflect this change. | ||
| * **implementors**: those who maintain a library or client which implements specs (see below) | ||
| * **developer community**: those who build tools that are expected to support NGFFs (e.g., napari, BDV, Viv) | ||
| * **[the ngff group](https://forum.image.sc/g/ngff)**: those who have actively signed up for calls, feedback, etc. | ||
| * and, of course, the wider community of users. | ||
|
|
||
| ## Implementation | ||
|
|
||
| Typically a specification proposal included a single PR which updated the `latest` version | ||
| of the specification in the `index.bs` file and additionally included examples and schema | ||
| files representing the changes. | ||
|
|
||
| Once data could be generated by one of the implementations, there was then a | ||
| general attempt to update all implementing libraries (ome-zarr-py, n5-zarr, | ||
| [validator](https://github.com/ome/ome-ngff-validator/), etc.) and implementing | ||
| clients (MoBIE, ViZarr, napari-ome-zarr, neuroglancer, ITK, etc.). Minimally, | ||
| one update in each of the three primary languages, Java, Python and Javascript, | ||
| was undertaken. | ||
|
|
||
|
|
||
| ### Phases | ||
|
|
||
| The phases below were sometimes concurrent and/or in a different order. | ||
|
|
||
| * **Proposal**: an informal statement that someone would like to lead an effort | ||
| to change the specification. | ||
| * **Issue opened** (optional): a slightly more formal statement of the purposes of a | ||
| Proposal that tracks all of the associated work. | ||
| * **Community call**: an open call, usually on Zoom, announced under | ||
| <https://forum.image.sc/tag/ome-ngff> where a proposal might be discussed. | ||
| * **Hackathon**: an open, often in-person, meeting to work on a Proposal. | ||
| * **Drafting**: period during which the specification is being actively | ||
| modified. | ||
| * **PR Opened**: a change to the specification including the normative text, | ||
| examples, schemas and schema tests. | ||
| * **Discussions**: once a formal change has been opened, period of time during | ||
| which comments and feedback are collected and changes are made. | ||
| * **PR Merged**: no further changes are intended and the specification is | ||
| considered acceptable to be part of "latest". | ||
| * **Acceptance**: the changes to "latest" are considered acceptable for a | ||
| release and are ported to the appropriate version directory. | ||
| * **Implementation**: support added to each of the libraries and clients | ||
| listed above. A differentiation may need to be made between core (MUST) and | ||
| additional (SHOULD) components. | ||
| * **Release**: an NGFF specification version was formally released by adding the | ||
| appropriate tag to the NGFF repository. | ||
|
|
||
| ## Drawbacks, risks, alternatives, and unknowns | ||
|
|
||
| Beyond a certain scale, the consensus model does not help maintainers of the | ||
| specification to move discussions forward. There is no clear arbiter of | ||
| decisions, and the timeline of discussions are not specified. A decision may | ||
| have been made, but without a clear record pull requests open for | ||
| implementation are effectively still in play. Additionally, authors were often | ||
| left with many separate questions on GitHub pull requests that needed answering | ||
| with no clear mechanism for managing those. | ||
|
|
||
| ## Future possibilities | ||
|
|
||
| Please see [RFC-1](../1/index). | ||
|
|
||
| ## Examples | ||
|
|
||
| * [5](https://github.com/ome/ngff/pull/5) HCS | ||
| * [3](https://github.com/ome/ngff/pull/3) labels | ||
| * [40](https://github.com/ome/ngff/pull/40) nested (0.2.0) | ||
| * [46](https://github.com/ome/ngff/pull/46) and [57](https://github.com/ome/ngff/pull/57) (axes) | ||
| * [64](https://github.com/ome/ngff/pull/64) table (closed) | ||
| * [112](https://github.com/ome/ngff/pull/112) bioformats2raw | ||
|
|
||
| [IETF RFC 2119]: https://tools.ietf.org/html/rfc2119 |