From 75bb34898cda09ca6ee8ded8aec1e99ad78ab02b Mon Sep 17 00:00:00 2001 From: John Collier Date: Thu, 10 Dec 2020 15:16:12 -0500 Subject: [PATCH 01/14] Add doc outlining the version and release process Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 70 ++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/proposals/versioning-and-release.md diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md new file mode 100644 index 000000000..f1f7d1c41 --- /dev/null +++ b/docs/proposals/versioning-and-release.md @@ -0,0 +1,70 @@ +# Devfile Versioning and Release Process +This design document outlines the proposed versioning and release process for the Devfile spec. + +This document summarizes parts from he Devfile API technical meeting slides presented by @davidfestal back in October, and I recommend having a read through of it: https://docs.google.com/presentation/d/1ohM1HzPB59a3ajvB7rVWJkKONLBAuT0mb5P20_A6vLs/edit#slide=id.g8fc722bef9_1_8 + +## Versioning + +The following sections outline how we version the Devfile Kubernetes API, as well as the JSON schema generated from the API. + +### Kubernetes API +The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the single source of truth for the Devfile spec. It’s defined under `pkg/apis/` and contains the Go structs that are used by the devworkspace operator and devfile library. It's also where the Devfile JSON schema is generated from. + +**Versioning Scheme**: [Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning) (e.g. v1alpha1, v1beta2, v1, v2, etc) + +**Update Process**: + + 1) Add a new folder in the source repository (`pkg/apis/workspaces` in `devfile/api`) + 2) Add a schema and version in the CRD manifests + 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. + 4) Update the devworkspace operator and devfile library to consume the Go structs in the new API version, as needed. + +**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutelyneeded - for **big** changes or backwards incompatible changes. + +### Devfile JSON Schema + +As mentioned above, the Devfile JSON schema is generated from the Go structs defined in the Devfile Kubernetes API. The latest JSON schema for a given API version is located under `schemas/` in the [devfile/api repo](https://github.com/devfile/api/). + +**Versioning Scheme**: Semver (major.minor.bugfix) + +**Update Process**: + + 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` + 2) Re-generate the json schema + 3) Publish new schema to devfile.io website + +**When to Update?** On each release of the schema, incremented based on the changes going in to the release (e.g. bugfix = comments / bugfixes, minor = larger and / or backwards compatible changes, major == breaking / backwards incompatible changes). K8S API version updates should also result in an appropriate increment of the schema version. + + +### Relationship Between K8s API version and JSON Schema Version + +The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go). + +As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the latest JSON schema generated from the K8S API. + +## Release Process +The following steps outline the steps done to release a new version of the Devfile schema and publish its schemas to the devfile.io website + + 1) The release engineer tasked with creating the release clones the repository (and checks out the release branch if one already exists) + + 2) `make-release.sh ` is run: + + i) A release branch (the name corresponding to the schema version) is created, if one does not already exist. + + ii) The schema-version is updated in `pkg/apis/workspace//doc.go`. + + iii) New JSON schemas are generated to include the new schema version + + iv) A new commit including the changes + + v) Finally, a PR is opened to merge these changes into the release branch + + 3) Once the release PR is approved and merged, the release engineer creates a new release on GitHub based off the release branch that was just created and includes the generated devfile.json as a release artifact. + + 4) Once the release is published, GitHub actions run to publish the new schema to devfile.io. The “stable” schema is also updated to point to the new schema. + +An example pull request, `make-release.sh` script and GitHub action can be found here: +- [Release Pull Request](https://github.com/johnmcollier/api/pull/7) +- [make-release.sh](https://github.com/johnmcollier/api/blob/master/make-release.sh) +- [release-schema.yaml](https://github.com/johnmcollier/api/blob/master/.github/workflows/release-schema.yaml) + From ec5fcdd1f67ae9eb32a344739c8f677bde7833c7 Mon Sep 17 00:00:00 2001 From: John Collier Date: Thu, 10 Dec 2020 15:30:17 -0500 Subject: [PATCH 02/14] Update doc to be clear about the tag name Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index f1f7d1c41..455478a7a 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -59,7 +59,8 @@ The following steps outline the steps done to release a new version of the Devfi v) Finally, a PR is opened to merge these changes into the release branch - 3) Once the release PR is approved and merged, the release engineer creates a new release on GitHub based off the release branch that was just created and includes the generated devfile.json as a release artifact. + 3) Once the release PR is approved and merged, the release engineer creates a new release on GitHub based off the release branch that was just created and includes the generated `devfile.json` as a release artifact. + - The tag `v{major}.{minor}.{bugfix}` is used, to enable the new version of the API to be pulled in as a Go module. 4) Once the release is published, GitHub actions run to publish the new schema to devfile.io. The “stable” schema is also updated to point to the new schema. From 908b75fdb72f759c19dd3bfa25469ff81200cfde Mon Sep 17 00:00:00 2001 From: John Collier Date: Fri, 11 Dec 2020 09:48:15 -0500 Subject: [PATCH 03/14] Clarify Go module tag Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 455478a7a..99102d250 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -60,7 +60,7 @@ The following steps outline the steps done to release a new version of the Devfi v) Finally, a PR is opened to merge these changes into the release branch 3) Once the release PR is approved and merged, the release engineer creates a new release on GitHub based off the release branch that was just created and includes the generated `devfile.json` as a release artifact. - - The tag `v{major}.{minor}.{bugfix}` is used, to enable the new version of the API to be pulled in as a Go module. + - The tag `v{major}.{minor}.{bugfix}`, where the semver corresponds to the devfile schema version, is used to enable the new version of the API to be pulled in as a Go module. 4) Once the release is published, GitHub actions run to publish the new schema to devfile.io. The “stable” schema is also updated to point to the new schema. From 58337853d0194c8a9926317cd06798566a7dcceb Mon Sep 17 00:00:00 2001 From: John Collier Date: Fri, 11 Dec 2020 09:50:44 -0500 Subject: [PATCH 04/14] Fix formatting of bullet Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 99102d250..c91b25c28 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -19,7 +19,8 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. 4) Update the devworkspace operator and devfile library to consume the Go structs in the new API version, as needed. -**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutelyneeded - for **big** changes or backwards incompatible changes. +**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutelyneeded + - for **big** changes or backwards incompatible changes. ### Devfile JSON Schema From d1a209b994323b3bc9b60312afd4b3e8aaa4b994 Mon Sep 17 00:00:00 2001 From: John Collier Date: Fri, 11 Dec 2020 15:09:51 -0500 Subject: [PATCH 05/14] Update docs/proposals/versioning-and-release.md Co-authored-by: Angel Misevski --- docs/proposals/versioning-and-release.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index c91b25c28..edff06b91 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -39,7 +39,7 @@ As mentioned above, the Devfile JSON schema is generated from the Go structs def ### Relationship Between K8s API version and JSON Schema Version -The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go). +The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go`). As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the latest JSON schema generated from the K8S API. @@ -69,4 +69,3 @@ An example pull request, `make-release.sh` script and GitHub action can be found - [Release Pull Request](https://github.com/johnmcollier/api/pull/7) - [make-release.sh](https://github.com/johnmcollier/api/blob/master/make-release.sh) - [release-schema.yaml](https://github.com/johnmcollier/api/blob/master/.github/workflows/release-schema.yaml) - From dde7417be62d752e609f6480f6d35b83529c16e3 Mon Sep 17 00:00:00 2001 From: John Collier Date: Fri, 11 Dec 2020 15:09:57 -0500 Subject: [PATCH 06/14] Update docs/proposals/versioning-and-release.md Co-authored-by: Angel Misevski --- docs/proposals/versioning-and-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index edff06b91..b02b2c532 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -19,7 +19,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. 4) Update the devworkspace operator and devfile library to consume the Go structs in the new API version, as needed. -**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutelyneeded +**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed - for **big** changes or backwards incompatible changes. ### Devfile JSON Schema From d2cb4272a4b8fb0651e83ca05dd7c235037f5913 Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 14 Dec 2020 12:19:10 -0500 Subject: [PATCH 07/14] Address review comments Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 29 ++++++++++++++++-------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index c91b25c28..2d139c1a4 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -1,7 +1,7 @@ # Devfile Versioning and Release Process This design document outlines the proposed versioning and release process for the Devfile spec. -This document summarizes parts from he Devfile API technical meeting slides presented by @davidfestal back in October, and I recommend having a read through of it: https://docs.google.com/presentation/d/1ohM1HzPB59a3ajvB7rVWJkKONLBAuT0mb5P20_A6vLs/edit#slide=id.g8fc722bef9_1_8 +This document summarizes parts from the Devfile API technical meeting slides presented by @davidfestal back in October, and I recommend having a read through of it: https://docs.google.com/presentation/d/1ohM1HzPB59a3ajvB7rVWJkKONLBAuT0mb5P20_A6vLs/edit#slide=id.g8fc722bef9_1_8 ## Versioning @@ -12,36 +12,43 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s **Versioning Scheme**: [Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning) (e.g. v1alpha1, v1beta2, v1, v2, etc) -**Update Process**: +**When to Update**: - 1) Add a new folder in the source repository (`pkg/apis/workspaces` in `devfile/api`) + 1) Add a new folder in the source repository ([pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces) in [devfile/api](https://github.com/devfile/api/)) 2) Add a schema and version in the CRD manifests 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. 4) Update the devworkspace operator and devfile library to consume the Go structs in the new API version, as needed. -**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutelyneeded - - for **big** changes or backwards incompatible changes. +**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). + - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields) + - New, optional fields to the API do not necessarily require a version bump, but if it's a large change, it may be wise to bump the version. ### Devfile JSON Schema As mentioned above, the Devfile JSON schema is generated from the Go structs defined in the Devfile Kubernetes API. The latest JSON schema for a given API version is located under `schemas/` in the [devfile/api repo](https://github.com/devfile/api/). -**Versioning Scheme**: Semver (major.minor.bugfix) +**Versioning Scheme**: Semantic Versioning (major.minor.bugfix) -**Update Process**: +**When to Update**: 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` 2) Re-generate the json schema 3) Publish new schema to devfile.io website -**When to Update?** On each release of the schema, incremented based on the changes going in to the release (e.g. bugfix = comments / bugfixes, minor = larger and / or backwards compatible changes, major == breaking / backwards incompatible changes). K8S API version updates should also result in an appropriate increment of the schema version. +**When to Update?** On each release of the schema, incremented based on the changes going in to the release. E.g.: + + - major == breaking / backwards incompatible changes). + - minor == larger and / or backwards compatible changes + - bugfix == comments / bugfixes + +K8S API version updates should also result in an appropriate increment of the schema version. ### Relationship Between K8s API version and JSON Schema Version -The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go). +The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go`). -As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the latest JSON schema generated from the K8S API. +As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the matching JSON schema generated from the K8S API. ## Release Process The following steps outline the steps done to release a new version of the Devfile schema and publish its schemas to the devfile.io website @@ -65,6 +72,8 @@ The following steps outline the steps done to release a new version of the Devfi 4) Once the release is published, GitHub actions run to publish the new schema to devfile.io. The “stable” schema is also updated to point to the new schema. + 5) Make a release announcement on the devfile mailing list and slack channel + An example pull request, `make-release.sh` script and GitHub action can be found here: - [Release Pull Request](https://github.com/johnmcollier/api/pull/7) - [make-release.sh](https://github.com/johnmcollier/api/blob/master/make-release.sh) From b2749e776716e891799e86d0822f49254094de77 Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 14 Dec 2020 12:25:13 -0500 Subject: [PATCH 08/14] Be clear on how api tag corresponds to api version Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 31487813f..cad11df90 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -68,7 +68,7 @@ The following steps outline the steps done to release a new version of the Devfi v) Finally, a PR is opened to merge these changes into the release branch 3) Once the release PR is approved and merged, the release engineer creates a new release on GitHub based off the release branch that was just created and includes the generated `devfile.json` as a release artifact. - - The tag `v{major}.{minor}.{bugfix}`, where the semver corresponds to the devfile schema version, is used to enable the new version of the API to be pulled in as a Go module. + - The tag `v{major}.{minor}.{bugfix}`, where the `{major}.{minor}.{bugfix}` corresponds to the devfile schema version, is used to enable the new version of the API to be pulled in as a Go module. 4) Once the release is published, GitHub actions run to publish the new schema to devfile.io. The “stable” schema is also updated to point to the new schema. From 5ce66134a579ffa94da713e12e32ae96f5d70353 Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 14 Dec 2020 12:31:03 -0500 Subject: [PATCH 09/14] Address review comments further. Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index cad11df90..28cee7502 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -12,12 +12,12 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s **Versioning Scheme**: [Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning) (e.g. v1alpha1, v1beta2, v1, v2, etc) -**When to Update**: +**How to Update**: - 1) Add a new folder in the source repository ([pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces) in [devfile/api](https://github.com/devfile/api/)) + 1) Add a new folder for the version in the [devfile/api](https://github.com/devfile/api/) repository under [pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces). For example `pkg/apis/workspaces/v1` if bumping the K8S API version to `v1`. 2) Add a schema and version in the CRD manifests 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. - 4) Update the devworkspace operator and devfile library to consume the Go structs in the new API version, as needed. + 4) Update the devworkspace operator and devfile library to consume the Go structs in the new K8S API version, as needed. **When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields) @@ -25,11 +25,11 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s ### Devfile JSON Schema -As mentioned above, the Devfile JSON schema is generated from the Go structs defined in the Devfile Kubernetes API. The latest JSON schema for a given API version is located under `schemas/` in the [devfile/api repo](https://github.com/devfile/api/). +As mentioned above, the Devfile JSON schema is generated from the Go structs defined in the Devfile Kubernetes API. The latest JSON schema for a given K8S API version is located under `schemas/` in the [devfile/api repo](https://github.com/devfile/api/). **Versioning Scheme**: Semantic Versioning (major.minor.bugfix) -**When to Update**: +**How to Update**: 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` 2) Re-generate the json schema @@ -48,7 +48,7 @@ K8S API version updates should also result in an appropriate increment of the sc The Devfile JSON schema is generated from the Kubernetes API, and the version for the JSON schema is set in the doc.go file in the K8S API (`pkg/apis/workspace//doc.go`). -As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the matching JSON schema generated from the K8S API. +As we’re only updating the K8S API version when needed, but incrementing the schema version more frequently, this means that any given K8S API version may point to multiple, backwards-compatible, schema versions over its lifespan. The schema version under `schemas/` in [devfile/api repo](https://github.com/devfile/api/) points to the matching JSON schema generated from the K8S API. ## Release Process The following steps outline the steps done to release a new version of the Devfile schema and publish its schemas to the devfile.io website From a8bd7ece18630b8b5060b27ee25bc76716a68f8f Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 14 Dec 2020 14:10:41 -0500 Subject: [PATCH 10/14] Update docs/proposals/versioning-and-release.md Co-authored-by: Angel Misevski --- docs/proposals/versioning-and-release.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 28cee7502..853319952 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -19,7 +19,8 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. 4) Update the devworkspace operator and devfile library to consume the Go structs in the new K8S API version, as needed. -**When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). +**When to Update?** +As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields) - New, optional fields to the API do not necessarily require a version bump, but if it's a large change, it may be wise to bump the version. From b7bea8645e9ed1b67fc314d34dbcd55c48fde26f Mon Sep 17 00:00:00 2001 From: John Collier Date: Mon, 14 Dec 2020 14:10:54 -0500 Subject: [PATCH 11/14] Update docs/proposals/versioning-and-release.md Co-authored-by: Angel Misevski --- docs/proposals/versioning-and-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 853319952..2b9a26387 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -21,7 +21,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s **When to Update?** As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). - - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields) + - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields without a default) - New, optional fields to the API do not necessarily require a version bump, but if it's a large change, it may be wise to bump the version. ### Devfile JSON Schema From aff5339c5b2133da2b3273aa3612a661646f4474 Mon Sep 17 00:00:00 2001 From: John Collier Date: Wed, 16 Dec 2020 13:57:08 -0500 Subject: [PATCH 12/14] Cosmetic updates and cleanup Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 28cee7502..4308888be 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -12,7 +12,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s **Versioning Scheme**: [Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning) (e.g. v1alpha1, v1beta2, v1, v2, etc) -**How to Update**: +**How to Update?**: 1) Add a new folder for the version in the [devfile/api](https://github.com/devfile/api/) repository under [pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces). For example `pkg/apis/workspaces/v1` if bumping the K8S API version to `v1`. 2) Add a schema and version in the CRD manifests @@ -29,7 +29,7 @@ As mentioned above, the Devfile JSON schema is generated from the Go structs def **Versioning Scheme**: Semantic Versioning (major.minor.bugfix) -**How to Update**: +**How to Update?**: 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` 2) Re-generate the json schema @@ -37,7 +37,7 @@ As mentioned above, the Devfile JSON schema is generated from the Go structs def **When to Update?** On each release of the schema, incremented based on the changes going in to the release. E.g.: - - major == breaking / backwards incompatible changes). + - major == breaking / backwards incompatible changes. - minor == larger and / or backwards compatible changes - bugfix == comments / bugfixes From 9532b8b301679fb1fb51c666ed83f073299af7b8 Mon Sep 17 00:00:00 2001 From: John Collier Date: Thu, 17 Dec 2020 10:55:37 -0500 Subject: [PATCH 13/14] Update update process to be more clear Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index 37948b3be..f34b6e45c 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -16,7 +16,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s 1) Add a new folder for the version in the [devfile/api](https://github.com/devfile/api/) repository under [pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces). For example `pkg/apis/workspaces/v1` if bumping the K8S API version to `v1`. 2) Add a schema and version in the CRD manifests - 3) Generate the JSON schema from the API. New JSON schema will be located under `schemas/latest`. + 3) Go through the JSON schema update process outlined below to update the JSON schema version. 4) Update the devworkspace operator and devfile library to consume the Go structs in the new K8S API version, as needed. **When to Update?** @@ -34,7 +34,6 @@ As mentioned above, the Devfile JSON schema is generated from the Go structs def 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` 2) Re-generate the json schema - 3) Publish new schema to devfile.io website **When to Update?** On each release of the schema, incremented based on the changes going in to the release. E.g.: From 9e872fac4b32ff240b1781afc60de43132ad3032 Mon Sep 17 00:00:00 2001 From: John Collier Date: Thu, 17 Dec 2020 17:30:40 -0500 Subject: [PATCH 14/14] Cleanup of doc Signed-off-by: John Collier --- docs/proposals/versioning-and-release.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/proposals/versioning-and-release.md b/docs/proposals/versioning-and-release.md index f34b6e45c..182bb447b 100644 --- a/docs/proposals/versioning-and-release.md +++ b/docs/proposals/versioning-and-release.md @@ -12,7 +12,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s **Versioning Scheme**: [Kubernetes](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning) (e.g. v1alpha1, v1beta2, v1, v2, etc) -**How to Update?**: +**How to Update?** 1) Add a new folder for the version in the [devfile/api](https://github.com/devfile/api/) repository under [pkg/apis/workspaces](https://github.com/devfile/api/tree/master/pkg/apis/workspaces). For example `pkg/apis/workspaces/v1` if bumping the K8S API version to `v1`. 2) Add a schema and version in the CRD manifests @@ -20,6 +20,7 @@ The Devfile Kubernetes API (defined in https://github.com/devfile/api/) is the s 4) Update the devworkspace operator and devfile library to consume the Go structs in the new K8S API version, as needed. **When to Update?** + As incrementing the Kubernetes API version for Devfile is a relatively heavy process, and affects the library, only update the K8s API version when absolutely needed (for **big** changes or backwards incompatible changes). - Backwards incompatible changes are defined as any change in the schema that would cause K8S API validation errors on the old resource version (e.g. removed fields or new mandatory fields without a default) - New, optional fields to the API do not necessarily require a version bump, but if it's a large change, it may be wise to bump the version. @@ -30,12 +31,14 @@ As mentioned above, the Devfile JSON schema is generated from the Go structs def **Versioning Scheme**: Semantic Versioning (major.minor.bugfix) -**How to Update?**: +**How to Update?** 1) Update the schema version string in the `// +devfile:jsonschema:version=` annotation in `pkg/apis/workspace//doc.go` 2) Re-generate the json schema -**When to Update?** On each release of the schema, incremented based on the changes going in to the release. E.g.: +**When to Update?** + +On each release of the schema, incremented based on the changes going in to the release. E.g.: - major == breaking / backwards incompatible changes. - minor == larger and / or backwards compatible changes