From 923e536cfb99e98b5e4d10215c89d46ad1226dfa Mon Sep 17 00:00:00 2001
From: Matt Leader <mleader@redhat.com>
Date: Wed, 15 Nov 2023 17:16:23 -0500
Subject: [PATCH] fix broken link and add schema versioning info (#70)

* fix broken link and add schema versioning info

* describe changes to upgrade wf file

* refer to type
---
 docs/arcaflow/workflows/index.md      |  9 ++++-
 docs/arcaflow/workflows/output.md     |  2 +-
 docs/arcaflow/workflows/versioning.md | 57 +++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 docs/arcaflow/workflows/versioning.md

diff --git a/docs/arcaflow/workflows/index.md b/docs/arcaflow/workflows/index.md
index 9ee057a0..af0637a6 100644
--- a/docs/arcaflow/workflows/index.md
+++ b/docs/arcaflow/workflows/index.md
@@ -1,6 +1,13 @@
 # Creating Arcaflow workflows
 
-Arcaflow workflows consist of three parts:
+Arcaflow workflows consist of four parts:
+
+
+<h2>Version</h2>
+
+The schema version must be at the root of your workflow file. It indicates the semantic version of the workflow file structure being used.
+
+[Learn more about versioning &raquo;](versioning.md){ .md-button }
 
 <h2>Inputs</h2>
 
diff --git a/docs/arcaflow/workflows/output.md b/docs/arcaflow/workflows/output.md
index 7538b5a0..20b50d14 100644
--- a/docs/arcaflow/workflows/output.md
+++ b/docs/arcaflow/workflows/output.md
@@ -24,5 +24,5 @@ A common example of two mutually exclusive events could be the availability of y
 In this example taken from the [Arcaflow Workflows](https://github.com/arcalot/arcaflow-workflows/blob/main/example-workflow/workflow.yaml) project, the `success` output collects the data from the specified steps and inserts it into data storage. The `no-indexing` output collects the data, the error logs, and does not store the data.
 
 ```yaml
-{!https://raw.githubusercontent.com/arcalot/arcaflow-workflows/main/example-workflow/workflow.yaml [ln:90-100]!}
+{!https://raw.githubusercontent.com/arcalot/arcaflow-workflows/main/system-performance/sysbench/workflow.yaml [ln:90-100]!}
 ```
\ No newline at end of file
diff --git a/docs/arcaflow/workflows/versioning.md b/docs/arcaflow/workflows/versioning.md
new file mode 100644
index 00000000..fcace19b
--- /dev/null
+++ b/docs/arcaflow/workflows/versioning.md
@@ -0,0 +1,57 @@
+# Workflow schema versions
+
+## Valid version string
+
+All workflow schema versions conform to [semantic version 2.0.0](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions) with a major, minor, and patch version. In this document, since the prepended `v` is unnecessary it is not used. However, it is required as a value for the version key in your workflow file.
+
+Invalid version string for `workflow.yaml`.
+
+```yaml
+version: 0.2.0
+input:
+steps:
+outputs:
+```
+
+**Valid** version string for `workflow.yaml`.
+
+```yaml
+version: v0.2.0
+input:
+steps:
+outputs:
+```
+
+## Supported versions
+
+* 0.2.0
+
+## Compatibility Matrix
+
+
+| Workflow schema version | Arcaflow Engine release  |
+|---|---|
+| 0.2.0 | 0.9.0 |
+
+## Upgrading
+
+### 0.2.0
+
+For the configuration file, `config.yaml`, two types of deployers are now possible, `image` and `python`, so `deployer` has become `deployers`. Effectively, the `type` key has become the `deployer_name` key. The `deployer_name` key and value are **required** which means you must also have either the `image` key or the `python` key.
+
+```yaml
+deployers:
+  image:
+    deployer_name: docker|podman|kubernetes
+  python:
+    deployer_name: python
+```
+
+For your workflow file, `workflow.yaml`, the `version` key and value are **required**, and they must be at the root of the file.
+
+```yaml
+version: v0.2.0
+inputs: {}
+steps: {}
+outputs: {}
+```
\ No newline at end of file