From 5a1f912cba87ab060cd1e73bc34bb0f5e22b3927 Mon Sep 17 00:00:00 2001
From: Ali Maredia <amaredia@redhat.com>
Date: Wed, 17 Jul 2024 09:32:48 -0400
Subject: [PATCH] Proposal for versioning the ilab config file

Related to instructlab/instructlab/issues/1725

Signed-off-by: Ali Maredia <amaredia@redhat.com>
---
 .spellcheck-en-custom.txt          |  1 +
 docs/schema/ilab-config-version.md | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 docs/schema/ilab-config-version.md

diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt
index 77e804ba..119a2aa9 100644
--- a/.spellcheck-en-custom.txt
+++ b/.spellcheck-en-custom.txt
@@ -62,6 +62,7 @@ hardcoded
 hipBLAS
 ilab
 impactful
+incrementing
 Inferencing
 instantiation
 instructlab
diff --git a/docs/schema/ilab-config-version.md b/docs/schema/ilab-config-version.md
new file mode 100644
index 00000000..4426bf8b
--- /dev/null
+++ b/docs/schema/ilab-config-version.md
@@ -0,0 +1,25 @@
+# `ilab` Config.yaml Versioning
+
+## Problem Statement
+
+Currently the `ilab` CLI's configuration file, `config.yaml`, does not contain a version.
+
+The config file in `ilab` version `0.17` cannot be used in future versions of `ilab` due to new mandatory fields and changes to existing fields.
+
+As the configuration file grows, changes, and becomes more complex, versioning is necessary in order to support forwards and backwards compatibility.
+
+## Proposal
+
+The `ilab` configuration file has a new `version` field at the top level of the config.
+
+The value of `version` should start at `1.0.0`.
+
+## Future Considerations
+
+As future development of `ilab` occurs, ramifications and tooling for the versioning the configuration file will need to be determined for users and developers.
+
+Such considerations include but are not limited to:
+
+- Rules for incrementing the version number
+- Tooling to support forward compatibility of configuration files
+- Limits for the forward and backward compatibility of configuration files