Add versioning to custom SDG flow file format

Signed-off-by: Mark McLoughlin <markmc@redhat.com>

Author: markmc

docs/sdg/sdg-flow-yaml.md

@@ -25,6 +25,7 @@ block_configs = flow.render()
 The YAML file format will mirror the API and look like this:
 
 ```yaml
+version: 1.0
 block_configs:
   - block_type: LLMBlock
     block_config: # LLMBlock constructor kwargs
@@ -44,6 +45,29 @@ block_configs:
      drop_columns: ["judgment", "explanation"]
 ```
 
+## Versioning
+
+A mandatory `version` field in the YAML file expresses major and minor versions (e.g., 1.0, 1.1, 2.0).
+
+Compatibility rules
+
+1. If the major version of the YAML file is higher than the parser can handle, the parser should reject the file.
+2. If the minor version of the YAML file is higher than the highest version the parser is aware of, the parser should read the file but ignore any unrecognized content.
+3. If the file’s version is lower than the parser’s version, the parser should provide default values for any configuration introduced in later versions.
+
+Example parsing logic:
+
+```python
+def parse_custom_flow(content):
+    version = content['version']
+    major, minor = map(int, version.split('.'))
+
+    if major > PARSER_MAJOR:
+        raise IncompatibleVersionError("The custom flow file format is from a future major version.")
+    elif major <= PARSER_MAJOR and minor > PARSER_MINOR:
+        logger.warning("The custom flow file may have new features that will be ignored.")
+```
+
 ### Flow Params
 
 The following parameters are supplied to a Flow constructor and used by the render() method: