From c4e8ff3046f943a033e8cf6ac4fedde67d67f9af Mon Sep 17 00:00:00 2001 From: mferrera Date: Wed, 5 Feb 2025 14:46:29 +0100 Subject: [PATCH] DOC: Add schema versioning scheme --- docs/src/conf.py | 19 ++--- docs/src/exported_data_products.md | 2 +- docs/src/index.rst | 9 ++- docs/src/products/initial_inplace_volumes.md | 6 +- docs/src/schema_versioning.md | 85 ++++++++++++++++++++ 5 files changed, 107 insertions(+), 14 deletions(-) create mode 100644 docs/src/schema_versioning.md diff --git a/docs/src/conf.py b/docs/src/conf.py index aae55dbf4..2cb112256 100755 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -30,9 +30,6 @@ def filter(self, record: logging.LogRecord) -> bool: # -- General configuration --------------------------------------------- -# The full version, including alpha/beta/rc tags. -release = fmu.dataio.__version__ - extensions = [ "myst_parser", "pydantic_autosummary", @@ -111,17 +108,21 @@ def set_myst_substitutions() -> dict[str, str]: # The master toctree document. master_doc = "index" -# General information about the project. -project = "fmu.dataio" -current_year = date.today().year -copyright = f"Equinor {current_year} (fmu-dataio release {release})" - - exclude_patterns = ["_build"] pygments_style = "sphinx" +# General information about the project. +project = "fmu-dataio" +current_year = date.today().year +# The full version, including alpha/beta/rc tags. +release = fmu.dataio.__version__ +# The short version, like 3.0 +version = ".".join(release.split(".")[:2]) + html_theme = "furo" +html_title = f"{project} {version}" +copyright = f"Equinor {current_year} ({project} release {release})" # html_logo = "images/logo.png" # The name of an image file (within the static path) to use as favicon diff --git a/docs/src/exported_data_products.md b/docs/src/exported_data_products.md index f7d11beba..7d7f47d56 100644 --- a/docs/src/exported_data_products.md +++ b/docs/src/exported_data_products.md @@ -1,4 +1,4 @@ -# Data Product Exports +# Data product exports fmu-dataio exposes functions for the export of data products. These are _standardized results_ that must conform to particular data shapes defined in diff --git a/docs/src/index.rst b/docs/src/index.rst index 3109eeaea..4915e3b74 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -41,6 +41,13 @@ post-processing services, new and improved cloud-only version of Webviz and much preparations examples exported_data_products + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Developer Guides + + schema_versioning + datamodel/index dataio_3_migration apiref/modules - datamodel/index diff --git a/docs/src/products/initial_inplace_volumes.md b/docs/src/products/initial_inplace_volumes.md index ef95638e1..45359152e 100644 --- a/docs/src/products/initial_inplace_volumes.md +++ b/docs/src/products/initial_inplace_volumes.md @@ -1,4 +1,4 @@ -# Initial Inplace Volumes +# Initial inplace volumes This exports the initial inplace volumes of a single grid from within RMS. @@ -71,7 +71,7 @@ The payload may contain other columns than the standard columns listed above. However, when these columns are present, their type is validated. ``` -## Product Schema +## Product schema This product is made available with a validation schema that can be used by consumers. A reference to the URL where this schema is present within the @@ -85,7 +85,7 @@ consumers. A reference to the URL where this schema is present within the :exclude-members: dump ``` -### JSON Schema +### JSON schema You can view the schema embedded here: diff --git a/docs/src/schema_versioning.md b/docs/src/schema_versioning.md new file mode 100644 index 000000000..0fc51481f --- /dev/null +++ b/docs/src/schema_versioning.md @@ -0,0 +1,85 @@ +# Schema versioning + +This document describes how schemas produced by fmu-dataio are versioned, +under what circumstances version numbers change, and provides criteria for the +kind of version change (patch, minor, major) a schema change causes. + +```{note} +The version of fmu-dataio is decoupled from the versions of schemas it produces. +This means that a new version of fmu-dataio may cause no schema changes at +all. Similarly, a new version of fmu-dataio may cause just one schema version +to change, or even _all_ of them. + +There is no direct relationship between an fmu-dataio version and schema +versions aside from the fact that a schema version may have changed _with_ a +new fmu-dataio version. +``` + +## Schema version changes + +Schema versions follow [semantic versioning](http://semver.org/). This gives +every schema version a specific number in the form `X.Y.Z` where + +- `X` is the major version number, +- `Y` is the minor version number, +- `Z` is the patch version number (sometimes called the _micro_ version). + +Schema version numbers change when a schema is changed. When deciding what +version a changed schema should become the primary concern should be whether +or not the change being made is backward compatible. Backwards compatibility +is broken if metadata generated for and valid against a previous version is +invalid against the updated version. + +Therefore schema version numbers change like so. + +### Major + +Any schema change that **breaks backward compatibility** with metadata created +using the previous schema version. These scenarios are candidates for a major +version change: + +- Adding a new required field +- Removing a required or optional field +- Moving an optional field to a required field +- Adding a regular expression or stricter validation to a field + - **Example**: A string field applies a maximum length validation check +- Changing the name of a field + - **Example**: `datetime` is changed to `timestamp` +- Changing the type of a field + - **Example**: A float field is changed is changed to a float string +- Changing the data format of a field + - **Example**: A date field is changed from Unix timestamp to ISO 8601 string +- Splitting or merging fields + - **Example**: A `version` field is changed to `major`, `minor`, `patch` (or + vice versa) +- Removing a value from a controlled vocabulary + - **Example**: `OWC` is no longer a valid contact (_unlikely, but an example!_) +- Changing the cardinality of field + - **Example**: An array field of length 4 becomes an array of length 8 + +### Minor + +Any schema change that **retains backward compatibility** with metadata created +using the previous version. + +- Adding an optional field +- Making a required field optional +- Changing a field from a controlled vocabulary to free text without changing + the field type +- Removing a regular expression or validation from a field +- Adding alternative formats for the same data + - **Example**: `"YYYY-MM-DD"` exists, and now `"YYYY/MM/DD"` is allowed +- Adding a computed or derived field that _is not required to be present_. + - **Example**: A sha1 hash is computed on an object metadata is representing + - **Example**: A _deterministic_ UUID is computed on an object and its metadata + +### Patch + +Any change to **auxiliary information** that does not affect the structure or +semantics of the schema itself. Also, any bug fixes to the schema. + +- Adding or updating the field description to improve readability, add + context, or correct an error +- Adding or updating the field example, comment, or user-friendly name +- Extending a controlled vocabulary enumeration +- Fixing an incorrect regular expression or validation