Issue 565: Maturity Level Documentation (#566)

* update MSP and add maturity to docs * write MM documentation * review period revision
ga4gh · Oct 26, 2024 · de23c20 · de23c20
1 parent 52fd157
commit de23c20
Show file tree

Hide file tree

Showing 24 changed files with 262 additions and 4 deletions.
diff --git a/.requirements.txt b/.requirements.txt
@@ -3,7 +3,7 @@ jsonschema
 referencing
 ipython
 pyyaml
-ga4gh.gks.metaschema==0.3.0b13
+ga4gh.gks.metaschema==0.3.0b14
 sphinx ~= 7.2
 sphinx-rtd-theme ~= 1.2
 jupyterlab

diff --git a/docs/source/appendices/index.rst b/docs/source/appendices/index.rst
@@ -7,7 +7,7 @@ Appendices
    getting_involved    
    design_decisions
    development_process
-   mm_and_versioning
+   maturity_model
    future_plans
 
    implementations

diff --git a/docs/source/appendices/maturity_model.rst b/docs/source/appendices/maturity_model.rst
@@ -0,0 +1,153 @@
+.. _maturity-model:
+
+GKS Maturity Model
+!!!!!!!!!!!!!!!!!!
+
+The Genomic Knowledge Standards work stream is developing semantic data exchange 
+standards for federated genomic knowledge sharing. To address this, new technical 
+specifications are required, such as the VRS standard, which must be developed 
+and iterated upon through application across community implementations. This 
+creates a tension between the need to create products with enough stability for 
+initial community adoption, while ensuring that they can evolve with minimal 
+disruption to interoperate smoothly across a diverse set of genomic knowledge 
+resources. Mechanisms for communicating the stability, uptake, and development 
+of technical specifications are therefore of paramount importance to addressing 
+this balance.
+
+A maturity model is a useful mechanism for communicating varying stability across 
+product features (e.g. data classes or protocols) of a GKS standard. This is 
+needed to help data producers at each stage of the adoption lifecycle 
+decide on the appropriate time to engage and implement the standard. Product 
+features that have progressed through the maturity model should have an associated 
+progression of support from the GKS specification maintainers for message 
+generation, translation, and validation tooling.
+
+Here we define the maturity model and release process for developing and 
+maintaining GKS standards, with the goal of enabling  timely specification 
+adoption by the community.
+
+.. figure:: ../images/adoption_lifecycle.png
+    :width: 800
+
+    The Innovation Adoption Lifecycle. 
+
+    *The Innovation Adoption Lifecycle illustrates adoption rates (y-axis) for 
+    new technologies over time (x-axis). Innovators (leftmost on the time axis) 
+    are among the first to adopt a new technology, and laggards (rightmost) are 
+    among the last, reflecting the differing needs for innovation and stability 
+    by these community groups. Adopters in every category along the innovation 
+    adoption lifecycle benefit from communication about the maturity of technical 
+    specification components generated by the Genomic Knowledge Standards work 
+    stream. Communicating when a component is ready for implementation by groups 
+    along the innovation / stability spectrum is a primary goal of the maturity 
+    model, enabling adopters to engage at a time that is appropriate for their 
+    organizational needs.*
+
+Feature Maturity levels
+@@@@@@@@@@@@@@@@@@@@@@@
+
+.. figure:: ../images/maturity_levels.png
+    :width: 800
+
+    Product feature maturity level criteria and commitments.
+
+Product feature maturity levels are to be reviewed and advanced by consensus among 
+defined decision-makers following Work Stream and GA4GH processes, in consultation 
+with the associated product group membership. Factors to be considered for product 
+feature maturity advancement include the criteria specified in the above table, the 
+degree of adoption observed in the community, feedback provided by adopters, and 
+availability of specification maintainers to provide the level of support required.
+
+Developing a Draft Product Feature
+##################################
+
+**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`
+
+**Criteria**: Draft product feature development work should be based on real use 
+cases across multiple environments (aligned with `GA4GH Product Development 14.5`_). 
+Requirements may result directly from a `landscape analysis of the problem domain`_, 
+or may emerge in the course of technical specification development. It is expected 
+that the need for product features are first discussed in a community forum (e.g. 
+GitHub Discussions, GKS Work Stream calls).
+
+**Process**: Follow the GKS :ref:`development-process`. As part of this process, 
+it is expected that consensus among the decision-makers was reached and major design 
+decisions documented. Disagreements are resolved per Work Stream and GA4GH processes.
+
+Advancing from Draft to Trial Use
+#################################
+
+**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers`
+
+**Criteria**: Advancing a draft product feature to trial use should include at least two 
+independent product implementers that commit to supporting the draft product feature once 
+it has been advanced to trial use. At least one of these implementations must be open (aligned 
+with `GA4GH Product Development 14.8.3`_). Advancing a product feature to trial use also mandates 
+a minor version increment at the next release. As part of this process, it is expected that 
+consensus among the decision-makers was reached and major design decisions documented. Disagreement 
+resolution is handled per Work Stream and GA4GH processes.
+
+**Process**: A ballot release is created that describes draft models under evaluation for 
+advancement to trial use. A survey is sent to all Product Implementers that have indicated 
+they are implementing one or more features under evaluation for advance to Trial Use. This 
+survey includes:
+
+1. Name of Product Implementer
+#. Selection of a previously described implementation
+#. If (or if multiple, which) product feature(s) are suitable for advance to Trial Use
+#. Comments on response (e.g. explicit endorsement or description of gaps)
+
+There is a minimum 1-week review period for Product Implementers to respond, though this may
+be longer at the discretion of the product leads. More time for individual contributors may 
+be permitted on request.
+
+Advancing from Trial Use to Normative
+#####################################
+
+**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers`,
+:ref:`ws-leads`
+
+**Criteria**: A normative model should have demonstrated interoperability of multiple data 
+generation and data consumption implementations, and should include implementations beyond 
+those used to advance a model to Trial Use. Advancing a product feature to normative also 
+mandates a minor version increment at the next release. As part of this process, it is 
+expected that consensus among the decision-makers was reached and major design decisions 
+documented. Community consultation and disagreement resolution are handled per Work Stream 
+and GA4GH processes.
+
+.. _GA4GH Product Development 14.5: https://www.ga4gh.org/our-products/development-and-approval-process/#section_5:~:text=14.5%20Development%20work%20should%20be%20based%20on%20real%20use%20cases%20across%20multiple%20environments.
+.. _landscape analysis of the problem domain: https://www.ga4gh.org/our-products/development-and-approval-process/#section_4
+.. _GA4GH Product Development 14.8.3: https://www.ga4gh.org/our-products/development-and-approval-process/#section_5:~:text=14.8.3%20implementations
+
+Decision-maker roles
+@@@@@@@@@@@@@@@@@@@@
+
+A role is assumed by a person in developing GKS technical specifications and other 
+GA4GH products. There are several roles relevant to this document:
+
+.. _feature-developers:
+
+Feature Developers
+##################
+Feature developers are members of a product group assigned to implement a product feature.
+
+.. _product-implementers:
+
+Product Implementers
+####################
+Representatives of teams that will develop implementations. These typically include 
+(but are not limited to) Driver Project representatives that have committed to developing 
+the product as part of the GA4GH Product Development and Approval Process.
+
+.. _product-leads:
+
+Product Leads
+#############
+Designated leads of a product group, who are responsible for overseeing product development.
+
+.. _ws-leads:
+
+Work Stream Leads
+#################
+These are domain experts assigned by the GA4GH to coordinate and lead the activities of a 
+GA4GH Work Stream.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -67,6 +67,9 @@ def _parse_release_as_version(rls):
 todo_include_todos = True
 todo_emit_warnings = True
 
+# Number figures
+# numfig = True
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages. See the documentation for

diff --git a/docs/source/images/adoption_lifecycle.png b/docs/source/images/adoption_lifecycle.png
diff --git a/docs/source/images/maturity_levels.png b/docs/source/images/maturity_levels.png
diff --git a/schema/vrs/def/Adjacency.rst b/schema/vrs/def/Adjacency.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 The `Adjacency` class can represent either the termination of a sequence or the adjoining of the end of a sequence with the beginning of an adjacent sequence, potentially with an intervening linker sequence.

diff --git a/schema/vrs/def/Allele.rst b/schema/vrs/def/Allele.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 The state of a molecule at a :ref:`Location`.

diff --git a/schema/vrs/def/CisPhasedBlock.rst b/schema/vrs/def/CisPhasedBlock.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 An ordered set of co-occurring :ref:`variants <Variation>` on the same molecule.

diff --git a/schema/vrs/def/CopyNumberChange.rst b/schema/vrs/def/CopyNumberChange.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 An assessment of the copy number of a :ref:`Location` or a :ref:`Gene` within a system (e.g. genome, cell, etc.) relative to a baseline ploidy.

diff --git a/schema/vrs/def/CopyNumberCount.rst b/schema/vrs/def/CopyNumberCount.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 The absolute count of discrete copies of a :ref:`Location` or :ref:`Gene`, within a system (e.g. genome, cell, etc.).

diff --git a/schema/vrs/def/DerivativeMolecule.rst b/schema/vrs/def/DerivativeMolecule.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A molecule derived from segments of multiple adjoined molecular sequences, typically resulting from structural variation.

diff --git a/schema/vrs/def/Expression.rst b/schema/vrs/def/Expression.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 Representation of a variation by a specified nomenclature or syntax for a Variation object. Common examples of expressions for the description of molecular variation include the HGVS and ISCN nomenclatures.

diff --git a/schema/vrs/def/LengthExpression.rst b/schema/vrs/def/LengthExpression.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A sequence expressed only by its length.

diff --git a/schema/vrs/def/LiteralSequenceExpression.rst b/schema/vrs/def/LiteralSequenceExpression.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 An explicit expression of a Sequence.

diff --git a/schema/vrs/def/Range.rst b/schema/vrs/def/Range.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 An inclusive range of values bounded by one or more integers.
diff --git a/schema/vrs/def/ReferenceLengthExpression.rst b/schema/vrs/def/ReferenceLengthExpression.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 An expression of a sequence that is derived from repeating a subsequence of an associated :ref:`SequenceLocation`.

diff --git a/schema/vrs/def/Residue.rst b/schema/vrs/def/Residue.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A character representing a specific residue (i.e., molecular species) or groupings of these ("ambiguity codes"), using `one-letter IUPAC abbreviations <https://en.wikipedia.org/wiki/International_Union_of_Pure_and_Applied_Chemistry#Amino_acid_and_nucleotide_base_codes>`_ for nucleic acids and amino acids.
diff --git a/schema/vrs/def/SequenceLocation.rst b/schema/vrs/def/SequenceLocation.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A :ref:`Location` defined by an interval on a referenced :ref:`Sequence`.

diff --git a/schema/vrs/def/SequenceReference.rst b/schema/vrs/def/SequenceReference.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A sequence of nucleic or amino acid character codes.

diff --git a/schema/vrs/def/SequenceString.rst b/schema/vrs/def/SequenceString.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 A character string of :ref:`Residues <Residue>` that represents a biological sequence using the conventional sequence order (5’-to-3’ for nucleic acid sequences, and amino-to-carboxyl for amino acid sequences). IUPAC ambiguity codes are permitted in Sequence Strings.
diff --git a/schema/vrs/def/Terminus.rst b/schema/vrs/def/Terminus.rst
@@ -1,3 +1,9 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
 The `Terminus` data class provides a structure for describing the end (terminus) of a molecule. Structurally similar to Adjacency, but used for describing where a molecule terminates (instead of adjoining another molecule).

diff --git a/schema/vrs/def/TraversalBlock.rst b/schema/vrs/def/TraversalBlock.rst
@@ -1,6 +1,12 @@
+
+.. warning:: This data class is at a **draft** maturity level and may change
+    significantly in future releases. Maturity levels are described in 
+    the :ref:`maturity-model`.
+
+
 **Computational Definition**
 
-A component used to describe the orientation of a molecular variation within a DerivativeMolecule.
+A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule.
 
 **Information Model**
 

diff --git a/schema/vrs/json/TraversalBlock b/schema/vrs/json/TraversalBlock
@@ -11,7 +11,7 @@
          "orientation"
       ]
    },
-   "description": "A component used to describe the orientation of a molecular variation within a DerivativeMolecule.",
+   "description": "A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule.",
    "properties": {
       "id": {
          "type": "string",