Merge pull request #231 from joshmoore/rfc-1-comment-1

RFC 1 Updates

0.1/index.bs

@@ -513,7 +513,7 @@ Citing {#citing}
 ================
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.1)
-J. Moore, *et al*. Editors. Open Microscopy Environment Consortium, 20 November 2020.
+J. Moore, *et al*. Open Microscopy Environment Consortium, 20 November 2020.
 This edition of the specification is [https://ngff.openmicroscopy.org/0.1/](https://ngff.openmicroscopy.org/0.1/]).
 The latest edition is available at [https://ngff.openmicroscopy.org/latest/](https://ngff.openmicroscopy.org/latest/).
 [(doi:10.5281/zenodo.4282107)](https://doi.org/10.5281/zenodo.4282107)

0.2/index.bs

@@ -571,7 +571,7 @@ Citing {#citing}
 ================
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.2)
-J. Moore, *et al*. Editors. Open Microscopy Environment Consortium, 29 March, 2021.
+J. Moore, *et al*. Open Microscopy Environment Consortium, 29 March, 2021.
 This edition of the specification is [https://ngff.openmicroscopy.org/0.2/](https://ngff.openmicroscopy.org/0.2/]).
 The latest edition is available at [https://ngff.openmicroscopy.org/latest/](https://ngff.openmicroscopy.org/latest/).
 [(doi:10.5281/zenodo.4282107)](https://doi.org/10.5281/zenodo.4282107)

0.3/index.bs

@@ -581,7 +581,7 @@ Citing {#citing}
 ================
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.3)
-J. Moore, *et al*. Editors. Open Microscopy Environment Consortium, 20 November 2020.
+J. Moore, *et al*. Open Microscopy Environment Consortium, 20 November 2020.
 This edition of the specification is [https://ngff.openmicroscopy.org/0.3/](https://ngff.openmicroscopy.org/0.3/]).
 The latest edition is available at [https://ngff.openmicroscopy.org/latest/](https://ngff.openmicroscopy.org/latest/).
 [(doi:10.5281/zenodo.4282107)](https://doi.org/10.5281/zenodo.4282107)

0.4/index.bs

@@ -657,7 +657,7 @@ Citing {#citing}
 ================
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.4)
-J. Moore, *et al*. Editors. Open Microscopy Environment Consortium, 8 February 2022.
+J. Moore, *et al*. Open Microscopy Environment Consortium, 8 February 2022.
 This edition of the specification is [https://ngff.openmicroscopy.org/0.4/](https://ngff.openmicroscopy.org/0.4/]).
 The latest edition is available at [https://ngff.openmicroscopy.org/latest/](https://ngff.openmicroscopy.org/latest/).
 [(doi:10.5281/zenodo.4282107)](https://doi.org/10.5281/zenodo.4282107)

latest/index.bs

@@ -14,8 +14,6 @@ Local Boilerplate: copyright yes
 Boilerplate: style-darkmode off
 Markup Shorthands: markdown yes
 Editor: Josh Moore, University of Dundee (UoD) https://www.dundee.ac.uk, https://orcid.org/0000-0003-4028-811X
-Editor: Sébastien Besson, University of Dundee (UoD) https://www.dundee.ac.uk, https://orcid.org/0000-0001-8783-1429
-Editor: Constantin Pape, European Molecular Biology Laboratory (EMBL) https://www.embl.org/sites/heidelberg/, https://orcid.org/0000-0001-6562-7187
 Text Macro: NGFFVERSION 0.5-dev
 Abstract: This document contains next-generation file format (NGFF)
 Abstract: specifications for storing bioimaging data in the cloud.
@@ -609,7 +607,7 @@ Citing {#citing}
 ================
 
 [Next-generation file format (NGFF) specifications for storing bioimaging data in the cloud.](https://ngff.openmicroscopy.org/0.4)
-J. Moore, *et al*. Editors. Open Microscopy Environment Consortium, 8 February 2022.
+J. Moore, *et al*. Open Microscopy Environment Consortium, 8 February 2022.
 This edition of the specification is [https://ngff.openmicroscopy.org/0.4/](https://ngff.openmicroscopy.org/0.4/]).
 The latest edition is available at [https://ngff.openmicroscopy.org/latest/](https://ngff.openmicroscopy.org/latest/).
 [(doi:10.5281/zenodo.4282107)](https://doi.org/10.5281/zenodo.4282107)

rfc/1/comment_1.md

@@ -1,8 +1,12 @@
-# RFC 1
-*Review to RFC 1 from @LucaMarconato and @melonora.*
+# Comment to [RFC 1](../1) from @LucaMarconato and @melonora.*
+
+| Name                   | GitHub Handle | Institution          |
+|------------------------|---------------|----------------------|
+| Wouter-Michiel Vierdag | melonora      | EMBL                 |
+| Luca Marconato         | LucaMarconato | EMBL                 |
+
+## Comments on implementations
 
-## Comments
-### Comments on implementations
 - Currently diagram does not reflect text. Text says *"If sufficient endorsements, including two in-progress 
 implementations, are available, then the RFC can progress (S1) to the SPEC phase below."*. The "code" checks are not 
 visible in the diagram which could make someone think that implementation is only of importance at the end of the RFC 
@@ -38,11 +42,12 @@ based on this example in which case the comment would have the status of address
 author I would prefer the meaning "the review process lasts maximum 4 weeks", while as a reviewer I would prefer "I have 
 up to 4 weeks to submit the review".
 
-### Typos/minor edits
+## Typos/minor edits
+
 - This sentence under section 'Stakeholders' paragraph 2 is truncated: "However, once the draft has reached a certain 
 stage that it is ready for comments, Editors will merge it as a record of the fact that the suggestion."
 
-### Consistency between the diagram and text description
+## Consistency between the diagram and text description
 
 - The sentence "However, once the draft has reached a certain stage that it is ready for comments, Editors will merge 
 it as a record of the fact that the suggestion." seems not to be reflected in the diagram.
@@ -52,4 +57,4 @@ already in the RFC phase.
 - Related to above, we suggest to use the same wording in the diagram and in the text: for instance the "RFC persists" 
 wording is not present in the text.
 - The diagram doesn't contain the equivalent points for the 🕐 comments that are present in the text. I would consider 
-unifying the clocks and the traffic lights.
+unifying the clocks and the traffic lights.

rfc/1/comment_2.md

@@ -0,0 +1,61 @@
+# Comment to [RFC 1](../1) from @thewtex
+
+| Name                   | GitHub Handle | Institution          |
+|------------------------|---------------|----------------------|
+| Matt McCormick         | thewtex       | ITK                  |
+
+## Comments from the original issue
+
+Wow, spectacular @joshmoore !
+
+I love :heart_eyes: :
+
+- The well-defined process!
+- Building on the process of arguably the most successful and impactful efforts for interoperability, the internet.
+- Multiple stages for incremental evolution and improvements.
+- A process that promotes a "defaults to yes" as opposed to "defaults to no" so we can progress and effort is not wasted.
+- Artifacts that result in a clear record of what has been proposed and discussed.
+- The diagram that provides a succinct high-level overview.
+- The time limits at stages.
+- A recognition in the process that full consensus is not what will allow the community to move forward, which is what we all really want.
+- The process essentially utilizes the same GitHub pull request-based system, but formalizes the phases and content, and ensures drafts and reviews and responses are more easily navigated.
+
+Regarding possible areas of improvement, there are a few tweaks we could make
+to have the intended effect. In particular, I am thinking of dynamics common in
+specification development where:
+
+- Changes are prematurely or unjustifiably suppressed because reviewers do not personally have interest in or and understanding of the change.
+- Strong-willed, arm-chair speculation on how a change should work without experience in implementation or usage.
+- Overly complex proposals that are difficult to implement.
+- Changes are rejected too early in an incubation stage.
+
+Another successful community process to cite that I think has lessons to learn
+from, also a W3C project, is the [WebAssembly
+process](https://github.com/WebAssembly/meetings/blob/main/process/phases.md).
+
+In particular, I think it is helpful to specify expectations on different
+degrees of implementations throughout the process. As we know, speculation on
+what should work well or how it should work is often clarified or modified
+during implementation and usage. There is also an iterative, evolutionary
+process to a final specification and implementation for good specifications. It
+is also helpful to clarify the specifics of a proposal to reviewers with a
+concrete example. And concerns about the impact of the complexity of a change
+on practical deployment are often resolved with reference implementation(s). By
+evolving an implementation with the spec, even if the implementation lags a
+bit, this helps avoid inconsistencies, which can be problematic even if it is
+just schema / documentation inconsistencies.
+
+The following changes could help address these issues with this in mind:
+
+1. Reserve input from Reviewers and Commenters until a spec has gone into the
+   RFC stage (I am afraid we may not see a practical difference with the status
+   quo otherwise).
+2. Before exiting the DRAFT phase, request some *partial* implementation
+   reference to link to.
+3. Before exiting the RFC phase, a *full* implementation with a *test suite* is
+   required.
+4. Before entering the SPEC adopted status, there must be at least two
+   implementations for the spec in the community.
+
+*Editor's note: See https://github.com/ome/ngff/pull/222 for the further
+discussion of these issues.*

rfc/1/index.md

@@ -5,11 +5,16 @@ Definition of the NGFF RFC process
 
 ## Status
 
-This RFC is currently under review (D4).
+This RFC is currently being responded to (R4).
 
-| Name       | GitHub Handle | Institution       | Date       | Status |
-|------------|---------------|-------------------|------------|--------|
-| Josh Moore | joshmoore     | German BioImaging | 2023-12-23 | Author |
+| Name                                     | GitHub Handle             | Institution            | Date         | Status                                              |
+| ---------------------------------------- | ------------------------- | ---------------------- | ------------ | --------------------------------------------------- |
+| Josh Moore                               | joshmoore                 | German BioImaging      | 2023-12-23   | Author ([PR](https://github.com/ome/ngff/pull/222)) |
+| Virginia Scarlett, _et al._              |                           | Janelia                | 2024-02-26   | [Review](./review_2.html)                           |
+| Kevin Yamauchi, Virginie Uhlmann         |                           | ETH, BiovisionCenter   | 2024-03-05   | [Review](./review_1.html)                           |
+| Matthew Hartley                          |                           | EMBL-EBI               | 2024-03-05   | [Review](./review_3.html)                           |
+| Wouter-Michiel Vierdag, Luca Marconato   | melonora, LucaMarconato   | EMBL                   | 2024-01-13   | [Comment](./comment_1.html)                         |
+| Matt McCormick                           | thewtex                   | ITK                    | 2024-01-09   | [Comment](./comment_2.html)                         |
 
 ## Overview
 
@@ -67,7 +72,7 @@ process and making that readily visible (c) ultimately driving the
 implementation of specifications in order to get working solutions into the
 hands of the bioimaging community. The process should **NOT** prevent future
 discussions on any adopted RFCs but instead will encourage continued
-improvement and evolution through discussions of _further_RFCs.
+improvement and evolution through discussions of _further_ RFCs.
 
 ## Requirements
 
@@ -79,7 +84,7 @@ interpreted as described in IETF RFC 2119.
 
 This section lists the major stakeholders in the RFC process and provides an
 overview of their responsibilities and involvement in the process. For more
-details, see the “Implementation” section below.
+details, see the "Implementation" section below.
 
 **Authors** propose an idea for the RFC process and socialize the idea, e.g.,
 through an issue or community call, gaining **Endorsers** They then submit a
@@ -89,8 +94,8 @@ document under the `rfc/` subdirectory and it SHOULD follow the template
 provided. As described under the "DRAFT" section below, this document can be
 discussed for clarity following the standard PR process. However, once the
 draft has reached a certain stage that it is ready for comments, **Editors**
-will merge it as a record of the fact that the suggestion. It will then become
-available on https://ngff.openmicroscopy.org.
+will merge it as a record of the fact that the suggestion has been made, and
+it will then become available on https://ngff.openmicroscopy.org.
 
 **Endorsers** are non-**Author** supporters of an RFC, listed in a table.
 **Reviewers** who have given an "Accept" recommendation are also added to the
@@ -127,6 +132,15 @@ This description of the RFC process will refer frequently to the [visual diagram
 Readers may want to familiar themselves with it at this point.
 Identifiers such as "D1", "R2", "S3", refer to steps in that diagram.
 
+### Legend
+
+Notes regarding specific requirements are called out throughout the text
+with the following symbols:
+
+> * 🕑 The clock symbol specifies definitive wait times within the process.
+> * 📂 The folder symbol specifies requirements on additions to the repository,
+>   for example an implementation or failing test.
+
 ### Phases
 
 The overall process is broken down into three phases: DRAFT phase before a
@@ -238,6 +252,8 @@ progress (S1) to the SPEC phase below. If there are no "Major" objections but
 still no consensus, the decision falls to the **Editors** (R7) who may also
 move the RFC to the SPEC phase (S0).
 
+> 📂 Two in-progress implementations required for progressing to S1.
+
 Otherwise, the RFC iterates through the process again. If the changes made by
 the **Authors** are significant, **Reviewers** may be asked to respond again
 (R2). Alternatively, **Editors** may send the text back to the **Authors** for
@@ -270,6 +286,20 @@ listed, the specification will be considered "adopted". The adopted
 specification will be slotted into a release version by the **Editors** and the
 **Authors** are encouraged to be involved in that release.
 
+>  📂 Two released implementations required for being adopted.
+
+### Decision-making
+
+Unless otherwise specified in the text, the following considerations are taken
+into account when making decisions regarding RFCs:
+
+ * **Prefer working examples**: whether an implementation of an RFC or a
+   failing test which exposes an issue in a proposal, working examples will
+   tend to carry more weight in decision making.
+ * **technical expertise**: all other considerations being equal, feedback
+   from stakeholders with more technical expertise in a matter under
+   consideration will tend to carry more weight in decision making.
+
 ## Drawbacks, risks, alternatives, and unknowns
 
 The primary **drawbacks**, **risks**, and **unknowns** of the proposal revolve
@@ -509,6 +539,12 @@ Definitions for terms used throughout this RFC have been collected below.
 * ZEP ("Zarr Enhancement Proposal") Decision-making process for the Zarr
   specification
 
+## Changelog
+
+| Date       | Description                             | Link                                    |
+| ---------- | --------------------------------------- | --------------------------------------- |
+| 2024-04-24 | Apply changes from comment 1            | <https://github.com/ome/ngff/pull/231>  |
+
 [dia]: diagram.png
 [tmpl]: template.md
 [iab]: https://www.ietf.org/about/groups/iab/