document workflow schema version #67
Conversation
|
|
||
| <h2>Version</h2> | ||
|
|
||
| The version section states which workflow schema version you are using to write your workflow. The latest supported workflow schema is `v0.1.0`. |
There was a problem hiding this comment.
It's going to be easy to overlook updating this static reference to the "latest supported workflow schema" in the future.
There was a problem hiding this comment.
I had the same thought, but I don't think we need a dynamic solution until we have more than 2 workflow schema versions.
There was a problem hiding this comment.
Are we aware of any good dynamic solution?
There was a problem hiding this comment.
I have done some research, and have not found a completely dynamic approach. From what I've seen folks still have to manually write down the mapping from file schema/format version to minimum engine version.
That mapping could be stored in a file which is read to dynamically generate the table.
There was a problem hiding this comment.
I have done some research, and have not found a completely dynamic approach. From what I've seen folks still have to manually write down the mapping from file schema/format version to minimum engine version.
That mapping could be stored in a file which is read to dynamically generate the table.
True, in any kind of a "build" environment: but it's also nice to be able to just go to GitHub and read the markdown file directly, in which case it would just be a blank. (Unless GitHub markdown has someway to include a text file inline?)
It may not really be necessary to call out "the latest supported version" here. You already link to the matrix.md with a table; which at least reduces the manual update to one file instead of two.
There was a problem hiding this comment.
I agree with @dbutenhof. I would recommend simply removing the explicit version reference here.
|
|
||
| <h2>Version</h2> | ||
|
|
||
| The version section states which workflow schema version you are using to write your workflow. The latest supported workflow schema is `v0.1.0`. |
There was a problem hiding this comment.
I have done some research, and have not found a completely dynamic approach. From what I've seen folks still have to manually write down the mapping from file schema/format version to minimum engine version.
That mapping could be stored in a file which is read to dynamically generate the table.
True, in any kind of a "build" environment: but it's also nice to be able to just go to GitHub and read the markdown file directly, in which case it would just be a blank. (Unless GitHub markdown has someway to include a text file inline?)
It may not really be necessary to call out "the latest supported version" here. You already link to the matrix.md with a table; which at least reduces the manual update to one file instead of two.
| @@ -0,0 +1,7 @@ | |||
| # Workflow and Engine Compatibility Matrix | |||
|
|
|||
| The workflow schema version uses the [semantic versioning 2.0.0 specification](https://semver.org/). In a workflow file definition, the schema version is prepended with a `v`. For example, `0.1.0` is written as `v0.1.0`. | |||
There was a problem hiding this comment.
Do you want to explicitly recommend always creating a new workflow with the latest version? 😸
There was a problem hiding this comment.
Yeah, we need to be careful. Because the documentation's version needs to match what the documentation itself is recommending.
|
Changes merged in pr 70 |
Changes introduced with this PR
By contributing to this repository, I agree to the contribution guidelines.