From 8a0fc62b0a85635834f846ed2cda814ba7b86d7b Mon Sep 17 00:00:00 2001 From: Josh Moore Date: Wed, 21 Feb 2024 18:54:40 +0100 Subject: [PATCH] Migrate process content from #132 --- rfc/0/index.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 137 insertions(+), 3 deletions(-) diff --git a/rfc/0/index.md b/rfc/0/index.md index 5c2549b8..2ee28c24 100644 --- a/rfc/0/index.md +++ b/rfc/0/index.md @@ -1,4 +1,138 @@ -RFC-0 -===== +# RFC-0: Consensus model -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, + . +* 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 **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 + 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