From 8ac2ff84337ea0159ab87d2ca8e1a89853f9dddf Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Thu, 28 Jan 2021 15:14:21 -0500 Subject: [PATCH 01/12] made migrating docs adhere to style guide --- .../assembly_migrating-to-devfile-v2.adoc | 7 ++- .../partials/proc_adding-event-bindings.adoc | 44 ++++++++++++++++--- .../partials/proc_migrating-commands.adoc | 32 +++++--------- .../partials/proc_migrating-components.adoc | 24 +++++++++- .../partials/proc_migrating-plug-ins.adoc | 18 ++++---- .../partials/proc_migrating-projects.adoc | 10 ++--- .../proc_migrating-schema-version.adoc | 8 ++-- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 20 ++++++--- 8 files changed, 104 insertions(+), 59 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index 00ff2030..f2e73f41 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -11,7 +11,7 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing v1.0 devfile to v2.0. +This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -24,10 +24,9 @@ This guide explains how to migrate an existing v1.0 devfile to v2.0. [role="_additional-resources"] .Additional resources -* New metadata: `version`. See link:https://github.com/che-incubator/devworkspace-api/issues/10[corresponding issue]. -* New mandatory metadata for plugins. See link:https://github.com/devfile/api/issues/31[corresponding issue]. +* New metadata: `version`, go to its link:https://github.com/che-incubator/devworkspace-api/issues/10[GitHub issue]. +* New mandatory metadata for plugins, go to its link:https://github.com/devfile/api/issues/31[GitHub issue]. ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] ifndef::parent-context-of-assembly_migrating-to-devfile-v2[:!context:] - diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index a013f442..4644112b 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,21 +2,22 @@ = Adding event bindings [role="_abstract"] +<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. +======= +This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. +>>>>>>> 0a125b6... made migrating docs adhere to style guide -.Prerequisites +Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. - - -.Procedure - -. Add an `events` section in the devfile, containing a list of `preStart` and `postStart` commands. +For an example, see the following yaml: ==== [source,yaml] ---- # v2.0 --- +<<<<<<< HEAD commands: - id: init-project apply: @@ -36,6 +37,33 @@ commands: commands: - copy-artifacts - init-cache +======= +components: + - container: + name: "copier" + image: '' + - container: + name: "maven" + image: '' + - plugin: + id: theia +Commands: +containerBuild: +reference: +composite: + + - exec: + name: "copyNeededFiles" + component: "copier" + commandLine: "cp somefile" + - exec: + name: "buildAll" + component: "maven" + commandLine: "mvn ..." + - vsCodeTask: + name: "openFile" + component: "theia" +>>>>>>> 0a125b6... made migrating docs adhere to style guide events: preStart: - init-project @@ -46,4 +74,8 @@ events: [role="_additional-resources"] .Additional resources +<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. +======= +To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. +>>>>>>> 0a125b6... made migrating docs adhere to style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 6339fc16..4d276c1a 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,33 +2,25 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate plug-ins to devfile v2. There ARE major changes in the `commands` section of the devfile. A command specified in a v1.0 devfile will NOT work as it is in a devfile v2.0. - -.Procedure - -. Command Groups: build,run,test,debug. -. Apply Command. -. Environment Varibables for a Specific Command. -. Renaming workdir into workingDir. -. Id and label for Composite Commands. -. Run exec Commands as Specific User. -. Devfile metadata: add a link to an external website. -. Stack/Devfile Matching Rules. +This section describes how to migrate commands to v2.0 devfiles. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. [role="_additional-resources"] .Additional resources -* Command Groups: build,run,test,debug. See https://github.com/che-incubator/devworkspace-api/issues/27[corresponding issue]. -* Apply Command. See https://github.com/devfile/api/issues/56[corresponding issue]. +To learn more about commands in v2.0 devfiles, go to the commands' GitHub issues on the following topics: + +* link:https://github.com/che-incubator/devworkspace-api/issues/27[Command groups: build,run,test,debug] + +* link:https://github.com/devfile/api/issues/56[Apply command] -* Environment Varibables for a Specific Command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/21[Environment varibables for a specific command] -* Renaming workdir into workingDir. See https://github.com/che-incubator/devworkspace-api/issues/22[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/22[Renaming workdir into workingDir] -* Id and label for Composite Commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/18[Id and label for composite commands] -* Run exec Commands as Specific User. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/34[Run exec commands as specific user] -* Devfile metadata: add a link to an external website. See https://github.com/che-incubator/devworkspace-api/issues/38[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/38[Devfile metadata: add a link to an external website] -* Stack/Devfile Matching Rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue]. \ No newline at end of file +* link:https://github.com/che-incubator/devworkspace-api/issues/40[Stack/devfile matching rules] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index fc886947..018cfe20 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,14 +2,19 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to devfile v2. There ARE major changes in the `components` section of the devfile. A component specified in a v1.0 devfile will NOT work as it is in a devfile v2.0. +This section describes how to migrate components to v2.0 devfiles. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. -.Procedure +To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +For an example, see the following yaml: + +<<<<<<< HEAD . Component is a polymorphic type + For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + +======= +>>>>>>> 0a125b6... made migrating docs adhere to style guide [source,yaml] ---- v2.0 @@ -25,6 +30,7 @@ components: - kubernetes: uri: https://.../mongo.yaml ---- +<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -42,11 +48,15 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. . Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. +======= +>>>>>>> 0a125b6... made migrating docs adhere to style guide [role="_additional-resources"] .Additional resources +To learn more about components in v2.0 devfiles, go to the components' GitHub issues on the following topics: +<<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. * Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. * Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. @@ -55,3 +65,13 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. * Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. * Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. * Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. +======= +* link:https://github.com/che-incubator/devworkspace-api/issues/4[Component is a polymophic type] +* link:https://github.com/che-incubator/devworkspace-api/issues/19[Shared volumes across components] +* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/che-incubator/devworkspace-api/issues/9[Replace alias with name] +* link:https://github.com/che-incubator/devworkspace-api/issues/8[Renaming dockerimage component type] +* link:https://github.com/che-incubator/devworkspace-api/issues/17[Specify sources path for containers] +* link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] +* link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] +>>>>>>> 0a125b6... made migrating docs adhere to style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 97e170a4..3a08a2b0 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -1,12 +1,10 @@ [id="proc_migrating-plug-ins_{context}"] -= Migrating plug-ins += Migrating plugins [role="_abstract"] -This section describes how to migrate plug-ins to devfile v2. There ARE major changes about the definition of plugins in a devfile. Plugins are now specified using a devfile. A plugin specified in a v1.0 meta.yaml will NOT work as it is in a devfile v2.0. +This section describes how to migrate plugins to v2.0 devfiles. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. Instead, specify a plugins using a devfile. -.Procedure - -. Plugins are now specified using a devfile. A plugin specified in a v1.0 meta.yaml will NOT work as it is in a devfile v2.0. +For an example of the new plugins, see the following yaml: [source,yaml] ---- @@ -28,9 +26,9 @@ metadata: firstPublicationDate: "2020-02-20" pluginType: che-theia-vsx # <== mandatory # for plugins - # Valid types: + # Valid types: # che-theia-vsx - # che-editor, + # che-editor, # che-theia-plugin, # che-theia-ext, # generic-service, @@ -58,7 +56,7 @@ components: name: m2 ---- -. And then can be referenced from a distinct devfile: +To reference a plugin from a distinct devfile, see the follow yaml: [source,yaml] ---- @@ -70,11 +68,11 @@ components: - plugin: name: java language server id: redhat/java11/0.57.0 # other then by `id`, a plugin - # can be referenced by `uri` and + # can be referenced by `uri` and # `kubernetes` ---- [role="_additional-resources"] .Additional resources -* See https://github.com/che-incubator/devworkspace-api/issues/31[corresponding issue]. +To learn more about plugins in v2.0 devfiles, go to the plugins' link:https://github.com/che-incubator/devworkspace-api/issues/31[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index e6616ef6..3031763b 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -2,12 +2,10 @@ = Migrating projects [role="_abstract"] -There are NO major changes in the `projects` section of the devfile. A project specified in a v1.0 devfile will work as it is in a devfile v2.0. +This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. -.Procedure +A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. -* The only major change is the addition of a new kind of project: `starterProjects`. Those are supposed to be used in interactive mode only (user pick one) and the git repo get not be cloned but only source code get copied (kind of what `git archive --remote= | tar -t` would do). -+ .starterProjects and projects description ==== [source,yaml] @@ -18,10 +16,10 @@ starterProjects: - name: "kafka-project" description: "Use this app to get a nodejs application for working with kafka" - name: "simple-project" - description: "Use this app to get a simple "hello world" nodejs application" + description: "Use this app to get a simple 'hello world' nodejs application" ---- ==== [role="_additional-resources"] .Additional resources -* See link:https://github.com/che-incubator/devworkspace-api/issues/42[corresponding issue]. +To learn more about starterProjects in v2.0 devfiles, go to starterProjects' link:https://github.com/che-incubator/devworkspace-api/issues/42[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index cf8d7dc2..6b97bb46 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -2,11 +2,11 @@ = Migrating schema version [role="_abstract"] -This section describes how to migrate schema version. +This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. -.Procedure +To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. -* Replace `apiVersion: 1.0.0` by `schemaVersion: 2.0.0`: +For an example, see the following yaml: [cols="1a,1a"] |==== @@ -34,4 +34,4 @@ metadata: [role="_additional-resources"] .Additional resources -* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue] +To learn more about the schema version in v2.0 devfiles, go to schema version's link:https://github.com/che-incubator/devworkspace-api/issues/7[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 961f590d..8f1d8c3c 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -2,18 +2,24 @@ = Refering to a parent devfile in a devfile [role="_abstract"] -It is possible to refer to another devfile as a parent to a given devfile. If a parent is specified, the devfile will inherit all behaviour from the parent. Part of the content of the parent can be overridden in the child devfile. That allows refering a devfile (the parent) from a distinct devfile and makes it possible to reuse in multiple devfiles the same parent (the stack). - .Prerequisites * xref:adding-schema-version-to-a-devfile.adoc[] * xref:adding-a-name-to-a-devfile.adoc[] -.Procedure +This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. + + + +You can refer to a parent devfile in three different ways: + +* registry + +* uri + +* kubernetes -* A parent devfile can be referenced in 3 different ways: `registry`, `uri` or `kubernetes`. -+ .Parent referred by registry ==== Using its `id` if it has been published in a registry. @@ -28,7 +34,7 @@ parent: registry: https://devfile-registry.io/ ---- ==== -+ + .Parent referred by uri ==== Using the URI if it has been published on a static http server (like gist or pastebin). @@ -42,7 +48,7 @@ parent: uri: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml ---- ==== -+ + .Parent identified by a Kubernetes resource ==== Using a Kubernetes resource name and namespace if it has been deployed on a Kubernete cluster. From 5ac121b38bc9c4245b63c8ea65bb80967d4d8777 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Fri, 12 Mar 2021 11:55:26 -0500 Subject: [PATCH 02/12] brought back the procedures, updated links, more changes to content for consistency and style guide --- .../assembly_migrating-to-devfile-v2.adoc | 6 ++-- .../partials/proc_adding-event-bindings.adoc | 15 ++++++++-- .../partials/proc_migrating-commands.adoc | 29 +++++++++++++------ .../partials/proc_migrating-components.adoc | 28 ++++++++++++++---- .../partials/proc_migrating-plug-ins.adoc | 20 ++++++++----- .../partials/proc_migrating-projects.adoc | 7 ++++- .../proc_migrating-schema-version.adoc | 13 +++++---- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 15 ++++++---- 8 files changed, 95 insertions(+), 38 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index f2e73f41..2cfcb66c 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -24,8 +24,10 @@ This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. [role="_additional-resources"] .Additional resources -* New metadata: `version`, go to its link:https://github.com/che-incubator/devworkspace-api/issues/10[GitHub issue]. -* New mandatory metadata for plugins, go to its link:https://github.com/devfile/api/issues/31[GitHub issue]. +For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: + +* link:https://github.com/devfile/api/issues/10[Devfile schema] +* link:https://github.com/devfile/api/issues/31[Plugin mechanism] ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 4644112b..867db51c 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -8,10 +8,14 @@ Commands can be bound to events to form four different types of events: `preStar This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. >>>>>>> 0a125b6... made migrating docs adhere to style guide +.Prerequisites + Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. -For an example, see the following yaml: +.Procedure +. Add an `events` section in the devfile, containing a list of `preStart` and `postStart` commands. ++ ==== [source,yaml] ---- @@ -71,11 +75,18 @@ events: - pre-compile-cmd ---- ==== - ++ [role="_additional-resources"] .Additional resources <<<<<<< HEAD +<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. ======= To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= + +For a deeper understanding of adding events, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 4d276c1a..0b9ce134 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,25 +2,36 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to v2.0 devfiles. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate commands to v2.0 devfiles. The command section of v2.0 devfile has major changes. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. + +.Procedure + +. Command groups: build, run, test, debug. +. Apply command. +. Environment variables for a specific command. +. Renaming workdir into workingDir. +. Id and label for composite commands. +. Run exec commands as specific user. +. Devfile metadata: add a link to an external website. +. Stack or devfile matching rules. [role="_additional-resources"] .Additional resources -To learn more about commands in v2.0 devfiles, go to the commands' GitHub issues on the following topics: +For a deeper understanding of migrating commands, go to the GitHub issues on the following topics: -* link:https://github.com/che-incubator/devworkspace-api/issues/27[Command groups: build,run,test,debug] +* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] * link:https://github.com/devfile/api/issues/56[Apply command] -* link:https://github.com/che-incubator/devworkspace-api/issues/21[Environment varibables for a specific command] +* link:https://github.com/devfile/api/issues/21[Environment variables for a specific command] -* link:https://github.com/che-incubator/devworkspace-api/issues/22[Renaming workdir into workingDir] +* link:https://github.com/devfile/api/issues/22[Renaming workdir into workingDir] -* link:https://github.com/che-incubator/devworkspace-api/issues/18[Id and label for composite commands] +* link:https://github.com/devfile/api/issues/18[Id and label for composite commands] -* link:https://github.com/che-incubator/devworkspace-api/issues/34[Run exec commands as specific user] +* link:https://github.com/devfile/api/issues/34[Run exec commands as specific user] -* link:https://github.com/che-incubator/devworkspace-api/issues/38[Devfile metadata: add a link to an external website] +* link:https://github.com/devfile/api/issues/38[Devfile metadata: add a link to an external website] -* link:https://github.com/che-incubator/devworkspace-api/issues/40[Stack/devfile matching rules] +* link:https://github.com/devfile/api/issues/40[Stack or devfile matching rules] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index 018cfe20..1473e06a 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,12 +2,11 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to v2.0 devfiles. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate components to v2.0 devfiles. The components section of v2.0 devfile has major changes. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. -To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. - -For an example, see the following yaml: +.Procedure +<<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type + @@ -15,6 +14,10 @@ For a better syntax validation component now is defined as a polymorphic type an + ======= >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. ++ +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] ---- v2.0 @@ -31,6 +34,7 @@ components: uri: https://.../mongo.yaml ---- <<<<<<< HEAD +<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -51,11 +55,15 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. ======= >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= ++ +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [role="_additional-resources"] .Additional resources -To learn more about components in v2.0 devfiles, go to the components' GitHub issues on the following topics: +For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +<<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. * Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. @@ -75,3 +83,13 @@ To learn more about components in v2.0 devfiles, go to the components' GitHub is * link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] * link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +* link:https://github.com/devfile/api/issues/4[Component is a polymophic type] +* link:https://github.com/devfile/api/issues/19[Shared volumes across components] +* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/devfile/api/issues/9[Replace alias with name] +* link:https://github.com/devfile/api/issues/8[Renaming dockerimage component type] +* link:https://github.com/devfile/api/issues/17[Specify sources path for containers] +* link:https://github.com/devfile/api/issues/14[Specify size of volume for component] +* link:https://github.com/devfile/api/issues/33[Containers endpoints: routes and ingresses] +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 3a08a2b0..5c24a539 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,10 +2,13 @@ = Migrating plugins [role="_abstract"] -This section describes how to migrate plugins to v2.0 devfiles. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. Instead, specify a plugins using a devfile. +This section describes how to migrate plugins to v2.0 devfiles. The plugins section of v2.0 devfile has major changes. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. -For an example of the new plugins, see the following yaml: +.Procedure +. Specify a plugin using a devfile. + ++ [source,yaml] ---- v2.0 @@ -55,9 +58,9 @@ components: - volume: name: m2 ---- - -To reference a plugin from a distinct devfile, see the follow yaml: - ++ +. Reference a plugin from a distinct devfile. ++ [source,yaml] ---- v2.0 @@ -71,8 +74,11 @@ components: # can be referenced by `uri` and # `kubernetes` ---- - ++ [role="_additional-resources"] .Additional resources -To learn more about plugins in v2.0 devfiles, go to the plugins' link:https://github.com/che-incubator/devworkspace-api/issues/31[GitHub issue]. + +For a deeper understanding of migrating plugins, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/31[Plugin mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 3031763b..6e61e7fb 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -4,9 +4,12 @@ [role="_abstract"] This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. +.Procedure + A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. .starterProjects and projects description + ==== [source,yaml] ---- @@ -22,4 +25,6 @@ starterProjects: [role="_additional-resources"] .Additional resources -To learn more about starterProjects in v2.0 devfiles, go to starterProjects' link:https://github.com/che-incubator/devworkspace-api/issues/42[GitHub issue]. +For a deeper understanding of migrating projects, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/42[StarterProjects] diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 6b97bb46..b1034f06 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -4,10 +4,10 @@ [role="_abstract"] This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. -To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. - -For an example, see the following yaml: +.Procedure +. To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. ++ [cols="1a,1a"] |==== | @@ -29,9 +29,10 @@ metadata: name: devfile-sample ---- |==== - - ++ [role="_additional-resources"] .Additional resources -To learn more about the schema version in v2.0 devfiles, go to schema version's link:https://github.com/che-incubator/devworkspace-api/issues/7[GitHub issue]. +For a deeper understanding of migrating schema versions, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/7[SchemaVersion attribute] diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 8f1d8c3c..2d3574e3 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -10,15 +10,13 @@ This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. - +.Procedure You can refer to a parent devfile in three different ways: -* registry - -* uri - -* kubernetes +. registry +. uri +. kubernetes .Parent referred by registry ==== @@ -45,7 +43,12 @@ schemaVersion: 2.0.0 metadata: name: my-project-dev parent: +<<<<<<< HEAD uri: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml +======= + id: redhat/nodejs/11.6 + uri: https://raw.githubusercontent.com/devfile/registry/master/stacks/nodejs/devfile.yaml +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide ---- ==== From ff05d0c8cf662991c70896b2afbe74966f09b0e7 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Mon, 29 Mar 2021 11:12:38 -0400 Subject: [PATCH 03/12] more tweaks for consistent devfile versioning --- .../assembly_migrating-to-devfile-v2.adoc | 4 ++-- .../partials/proc_adding-event-bindings.adoc | 4 ++++ .../partials/proc_migrating-commands.adoc | 2 +- .../partials/proc_migrating-components.adoc | 10 ++++++++- .../partials/proc_migrating-plug-ins.adoc | 22 +++++++++---------- .../partials/proc_migrating-projects.adoc | 4 ++-- .../proc_migrating-schema-version.adoc | 4 ++-- 7 files changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index 2cfcb66c..b389551f 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -11,7 +11,7 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. +This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -27,7 +27,7 @@ This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: * link:https://github.com/devfile/api/issues/10[Devfile schema] -* link:https://github.com/devfile/api/issues/31[Plugin mechanism] +* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 867db51c..97545f35 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -3,10 +3,14 @@ [role="_abstract"] <<<<<<< HEAD +<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. ======= This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. +>>>>>>> d8b8834... more tweaks for consistent devfile versioning .Prerequisites diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 0b9ce134..850639d8 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,7 +2,7 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to v2.0 devfiles. The command section of v2.0 devfile has major changes. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate commands to devfiles v2.x. The command section of devfile v2.x has major changes. A command specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index 1473e06a..c41624e0 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,10 +2,11 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to v2.0 devfiles. The components section of v2.0 devfile has major changes. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate components to devfiles v2.x. The components section of devfiles v2.x has major changes. A component specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure +<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type @@ -16,6 +17,9 @@ For a better syntax validation component now is defined as a polymorphic type an >>>>>>> 0a125b6... made migrating docs adhere to style guide ======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +======= +. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. +>>>>>>> d8b8834... more tweaks for consistent devfile versioning + >>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] @@ -63,6 +67,7 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -85,6 +90,9 @@ For a deeper understanding of migrating components, go to the GitHub issues on t >>>>>>> 0a125b6... made migrating docs adhere to style guide ======= * link:https://github.com/devfile/api/issues/4[Component is a polymophic type] +======= +* link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] +>>>>>>> d8b8834... more tweaks for consistent devfile versioning * link:https://github.com/devfile/api/issues/19[Shared volumes across components] * link:https://github.com/devfile/api/issues/48[Out of main pod components] * link:https://github.com/devfile/api/issues/9[Replace alias with name] diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 5c24a539..b2e65115 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -1,12 +1,12 @@ [id="proc_migrating-plug-ins_{context}"] -= Migrating plugins += Migrating plug-ins [role="_abstract"] -This section describes how to migrate plugins to v2.0 devfiles. The plugins section of v2.0 devfile has major changes. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate plug-ins to devfiles v2.x. The plug-ins section of devfile v2.x has major changes. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. .Procedure -. Specify a plugin using a devfile. +. Specify a plug-in using a devfile. + [source,yaml] @@ -27,12 +27,12 @@ metadata: repository: https://github.../vscode-java category: Language firstPublicationDate: "2020-02-20" - pluginType: che-theia-vsx # <== mandatory - # for plugins + plug-inType: che-theia-vsx # <== mandatory + # for plug-ins # Valid types: # che-theia-vsx # che-editor, - # che-theia-plugin, + # che-theia-plug-in, # che-theia-ext, # generic-service, # generic-ui @@ -59,7 +59,7 @@ components: name: m2 ---- + -. Reference a plugin from a distinct devfile. +. Reference a plug-in from a distinct devfile. + [source,yaml] ---- @@ -68,9 +68,9 @@ v2.0 devfile.yaml --- components: -- plugin: +- plug-in: name: java language server - id: redhat/java11/0.57.0 # other then by `id`, a plugin + id: redhat/java11/0.57.0 # other then by `id`, a plug-in # can be referenced by `uri` and # `kubernetes` ---- @@ -79,6 +79,6 @@ components: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating plugins, go to the GitHub issue on the following topic: +For a deeper understanding of migrating plug-ins, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/31[Plugin mechanism] +* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 6e61e7fb..6d7d3d62 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -2,11 +2,11 @@ = Migrating projects [role="_abstract"] -This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. +This section describes how to migrate projects to devfiles v2.x. A project specified in a devfile v1.x still works in a devfile v2.x. .Procedure -A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. +A major change in devfiles v2.x is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. .starterProjects and projects description diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index b1034f06..3b07374c 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -2,11 +2,11 @@ = Migrating schema version [role="_abstract"] -This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. +This section describes how to migrate a schema version to devfiles v2.x. A schema version specified in a devfile v1.x still works in a devfile v2.x. .Procedure -. To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. +. To migrate a schema version from devfiles v1.x to devfiles v2.x, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. + [cols="1a,1a"] |==== From 4caff9da21cf5783e2fc5d2dbf9c27df24252531 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Tue, 6 Apr 2021 15:38:24 -0400 Subject: [PATCH 04/12] fixed merge conflicts --- .../partials/proc_adding-event-bindings.adoc | 36 ------------------- .../partials/proc_migrating-components.adoc | 17 --------- 2 files changed, 53 deletions(-) diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 97545f35..814a577a 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -3,12 +3,8 @@ [role="_abstract"] <<<<<<< HEAD -<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. ======= -This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. >>>>>>> d8b8834... more tweaks for consistent devfile versioning @@ -25,7 +21,6 @@ Add an `events` section in your devfile and make sure it contains a list of `pre ---- # v2.0 --- -<<<<<<< HEAD commands: - id: init-project apply: @@ -45,33 +40,6 @@ commands: commands: - copy-artifacts - init-cache -======= -components: - - container: - name: "copier" - image: '' - - container: - name: "maven" - image: '' - - plugin: - id: theia -Commands: -containerBuild: -reference: -composite: - - - exec: - name: "copyNeededFiles" - component: "copier" - commandLine: "cp somefile" - - exec: - name: "buildAll" - component: "maven" - commandLine: "mvn ..." - - vsCodeTask: - name: "openFile" - component: "theia" ->>>>>>> 0a125b6... made migrating docs adhere to style guide events: preStart: - init-project @@ -83,12 +51,8 @@ events: [role="_additional-resources"] .Additional resources <<<<<<< HEAD -<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. ======= -To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= For a deeper understanding of adding events, go to the GitHub issue on the following topic: diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index c41624e0..a45e0737 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -6,7 +6,6 @@ This section describes how to migrate components to devfiles v2.x. The component .Procedure -<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type @@ -14,8 +13,6 @@ This section describes how to migrate components to devfiles v2.x. The component For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + ======= ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. ======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. @@ -38,7 +35,6 @@ components: uri: https://.../mongo.yaml ---- <<<<<<< HEAD -<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -56,8 +52,6 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. . Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. -======= ->>>>>>> 0a125b6... made migrating docs adhere to style guide ======= + @@ -67,7 +61,6 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. For a deeper understanding of migrating components, go to the GitHub issues on the following topics: -<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -79,16 +72,6 @@ For a deeper understanding of migrating components, go to the GitHub issues on t * Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. * Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. ======= -* link:https://github.com/che-incubator/devworkspace-api/issues/4[Component is a polymophic type] -* link:https://github.com/che-incubator/devworkspace-api/issues/19[Shared volumes across components] -* link:https://github.com/devfile/api/issues/48[Out of main pod components] -* link:https://github.com/che-incubator/devworkspace-api/issues/9[Replace alias with name] -* link:https://github.com/che-incubator/devworkspace-api/issues/8[Renaming dockerimage component type] -* link:https://github.com/che-incubator/devworkspace-api/issues/17[Specify sources path for containers] -* link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] -* link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= * link:https://github.com/devfile/api/issues/4[Component is a polymophic type] ======= * link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] From f72a9ee1d86a132c5ce71ffafa76700cf6e82c68 Mon Sep 17 00:00:00 2001 From: David Festal Date: Thu, 8 Apr 2021 14:50:17 +0000 Subject: [PATCH 05/12] Update devfile schema based on devfile/api@a313872749ed60b47fb015288bb6595df64dac33 --- .../attachments/jsonschemas/next/devfile.json | 1219 ----------------- 1 file changed, 1219 deletions(-) diff --git a/docs/modules/user-guide/attachments/jsonschemas/next/devfile.json b/docs/modules/user-guide/attachments/jsonschemas/next/devfile.json index e8f24e9c..126f5294 100644 --- a/docs/modules/user-guide/attachments/jsonschemas/next/devfile.json +++ b/docs/modules/user-guide/attachments/jsonschemas/next/devfile.json @@ -238,11 +238,6 @@ "required": [ "volume" ] - }, - { - "required": [ - "plugin" - ] } ], "properties": { @@ -578,612 +573,6 @@ }, "additionalProperties": false }, - "plugin": { - "description": "Allows importing a plugin.\n\nPlugins are mainly imported devfiles that contribute components, commands and events as a consistent single unit. They are defined in either YAML files following the devfile syntax, or as `DevWorkspaceTemplate` Kubernetes Custom Resources", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "id" - ] - }, - { - "required": [ - "kubernetes" - ] - } - ], - "properties": { - "commands": { - "description": "Overrides of commands encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "id" - ], - "oneOf": [ - { - "required": [ - "exec" - ] - }, - { - "required": [ - "apply" - ] - }, - { - "required": [ - "composite" - ] - } - ], - "properties": { - "apply": { - "description": "Command that consists in applying a given component definition, typically bound to a devworkspace event.\n\nFor example, when an `apply` command is bound to a `preStart` event, and references a `container` component, it will start the container as a K8S initContainer in the devworkspace POD, unless the component has its `dedicatedPod` field set to `true`.\n\nWhen no `apply` command exist for a given component, it is assumed the component will be applied at devworkspace start by default.", - "type": "object", - "properties": { - "component": { - "description": "Describes component that will be applied", - "type": "string" - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - } - }, - "additionalProperties": false - }, - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "composite": { - "description": "Composite command that allows executing several sub-commands either sequentially or concurrently", - "type": "object", - "properties": { - "commands": { - "description": "The commands that comprise this composite command", - "type": "array", - "items": { - "type": "string" - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "parallel": { - "description": "Indicates if the sub-commands should be executed concurrently", - "type": "boolean" - } - }, - "additionalProperties": false - }, - "exec": { - "description": "CLI Command executed in an existing component container", - "type": "object", - "properties": { - "commandLine": { - "description": "The actual command-line string\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - }, - "component": { - "description": "Describes component to which given action relates", - "type": "string" - }, - "env": { - "description": "Optional list of environment variables that have to be set before running the command", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "hotReloadCapable": { - "description": "Whether the command is capable to reload itself when source code changes. If set to `true` the command won't be restarted and it is expected to handle file changes on its own.\n\nDefault value is `false`", - "type": "boolean" - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "workingDir": { - "description": "Working directory where the command should be executed\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - } - }, - "additionalProperties": false - }, - "id": { - "description": "Mandatory identifier that allows referencing this command in composite commands, from a parent, or in events.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - } - }, - "additionalProperties": false - } - }, - "components": { - "description": "Overrides of components encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "container" - ] - }, - { - "required": [ - "kubernetes" - ] - }, - { - "required": [ - "openshift" - ] - }, - { - "required": [ - "volume" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "container": { - "description": "Allows adding and configuring devworkspace-related containers", - "type": "object", - "properties": { - "args": { - "description": "The arguments to supply to the command running the dockerimage component. The arguments are supplied either to the default command provided in the image or to the overridden command.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "command": { - "description": "The command to run in the dockerimage component instead of the default one provided in the image.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "cpuLimit": { - "type": "string" - }, - "cpuRequest": { - "type": "string" - }, - "dedicatedPod": { - "description": "Specify if a container should run in its own separated pod, instead of running as part of the main development environment pod.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "env": { - "description": "Environment variables used in this container.\n\nThe following variables are reserved and cannot be overridden via env:\n\n - `$PROJECTS_ROOT`\n\n - `$PROJECT_SOURCE`", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "image": { - "type": "string" - }, - "memoryLimit": { - "type": "string" - }, - "memoryRequest": { - "type": "string" - }, - "mountSources": { - "description": "Toggles whether or not the project source code should be mounted in the component.\n\nDefaults to true for all component types except plugins and components that set `dedicatedPod` to true.", - "type": "boolean" - }, - "sourceMapping": { - "description": "Optional specification of the path in the container where project sources should be transferred/mounted when `mountSources` is `true`. When omitted, the default value of /projects is used.", - "type": "string" - }, - "volumeMounts": { - "description": "List of volumes mounts that should be mounted is this container.", - "type": "array", - "items": { - "description": "Volume that should be mounted to a component container", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "description": "The volume mount name is the name of an existing `Volume` component. If several containers mount the same volume name then they will reuse the same volume and will be able to access to the same files.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "The path in the component container where the volume should be mounted. If not path is mentioned, default path is the is `/\u003cname\u003e`.", - "type": "string" - } - }, - "additionalProperties": false - } - } - }, - "additionalProperties": false - }, - "kubernetes": { - "description": "Allows importing into the devworkspace the Kubernetes resources defined in a given manifest. For example this allows reusing the Kubernetes definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "name": { - "description": "Mandatory name that allows referencing the component from other elements (such as commands) or from an external devfile that may reference this component through a parent or a plugin.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "openshift": { - "description": "Allows importing into the devworkspace the OpenShift resources defined in a given manifest. For example this allows reusing the OpenShift definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "volume": { - "description": "Allows specifying the definition of a volume shared by several other components", - "type": "object", - "properties": { - "ephemeral": { - "description": "Ephemeral volumes are not stored persistently across restarts. Defaults to false", - "type": "boolean" - }, - "size": { - "description": "Size of the volume", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "id": { - "description": "Id in a registry that contains a Devfile yaml file", - "type": "string" - }, - "kubernetes": { - "description": "Reference to a Kubernetes CRD of type DevWorkspaceTemplate", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string" - } - }, - "additionalProperties": false - }, - "registryUrl": { - "type": "string" - }, - "uri": { - "description": "Uri of a Devfile yaml file", - "type": "string" - } - }, - "additionalProperties": false - }, "volume": { "description": "Allows specifying the definition of a volume shared by several other components", "type": "object", @@ -1530,11 +919,6 @@ "required": [ "volume" ] - }, - { - "required": [ - "plugin" - ] } ], "properties": { @@ -1856,609 +1240,6 @@ }, "additionalProperties": false }, - "plugin": { - "description": "Allows importing a plugin.\n\nPlugins are mainly imported devfiles that contribute components, commands and events as a consistent single unit. They are defined in either YAML files following the devfile syntax, or as `DevWorkspaceTemplate` Kubernetes Custom Resources", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "id" - ] - }, - { - "required": [ - "kubernetes" - ] - } - ], - "properties": { - "commands": { - "description": "Overrides of commands encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "id" - ], - "oneOf": [ - { - "required": [ - "exec" - ] - }, - { - "required": [ - "apply" - ] - }, - { - "required": [ - "composite" - ] - } - ], - "properties": { - "apply": { - "description": "Command that consists in applying a given component definition, typically bound to a devworkspace event.\n\nFor example, when an `apply` command is bound to a `preStart` event, and references a `container` component, it will start the container as a K8S initContainer in the devworkspace POD, unless the component has its `dedicatedPod` field set to `true`.\n\nWhen no `apply` command exist for a given component, it is assumed the component will be applied at devworkspace start by default.", - "type": "object", - "properties": { - "component": { - "description": "Describes component that will be applied", - "type": "string" - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - } - }, - "additionalProperties": false - }, - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "composite": { - "description": "Composite command that allows executing several sub-commands either sequentially or concurrently", - "type": "object", - "properties": { - "commands": { - "description": "The commands that comprise this composite command", - "type": "array", - "items": { - "type": "string" - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "parallel": { - "description": "Indicates if the sub-commands should be executed concurrently", - "type": "boolean" - } - }, - "additionalProperties": false - }, - "exec": { - "description": "CLI Command executed in an existing component container", - "type": "object", - "properties": { - "commandLine": { - "description": "The actual command-line string\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - }, - "component": { - "description": "Describes component to which given action relates", - "type": "string" - }, - "env": { - "description": "Optional list of environment variables that have to be set before running the command", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug" - ] - } - }, - "additionalProperties": false - }, - "hotReloadCapable": { - "description": "Whether the command is capable to reload itself when source code changes. If set to `true` the command won't be restarted and it is expected to handle file changes on its own.\n\nDefault value is `false`", - "type": "boolean" - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "workingDir": { - "description": "Working directory where the command should be executed\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - } - }, - "additionalProperties": false - }, - "id": { - "description": "Mandatory identifier that allows referencing this command in composite commands, from a parent, or in events.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - } - }, - "additionalProperties": false - } - }, - "components": { - "description": "Overrides of components encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "container" - ] - }, - { - "required": [ - "kubernetes" - ] - }, - { - "required": [ - "openshift" - ] - }, - { - "required": [ - "volume" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "container": { - "description": "Allows adding and configuring devworkspace-related containers", - "type": "object", - "properties": { - "args": { - "description": "The arguments to supply to the command running the dockerimage component. The arguments are supplied either to the default command provided in the image or to the overridden command.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "command": { - "description": "The command to run in the dockerimage component instead of the default one provided in the image.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "cpuLimit": { - "type": "string" - }, - "cpuRequest": { - "type": "string" - }, - "dedicatedPod": { - "description": "Specify if a container should run in its own separated pod, instead of running as part of the main development environment pod.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "env": { - "description": "Environment variables used in this container.\n\nThe following variables are reserved and cannot be overridden via env:\n\n - `$PROJECTS_ROOT`\n\n - `$PROJECT_SOURCE`", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "image": { - "type": "string" - }, - "memoryLimit": { - "type": "string" - }, - "memoryRequest": { - "type": "string" - }, - "mountSources": { - "description": "Toggles whether or not the project source code should be mounted in the component.\n\nDefaults to true for all component types except plugins and components that set `dedicatedPod` to true.", - "type": "boolean" - }, - "sourceMapping": { - "description": "Optional specification of the path in the container where project sources should be transferred/mounted when `mountSources` is `true`. When omitted, the default value of /projects is used.", - "type": "string" - }, - "volumeMounts": { - "description": "List of volumes mounts that should be mounted is this container.", - "type": "array", - "items": { - "description": "Volume that should be mounted to a component container", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "description": "The volume mount name is the name of an existing `Volume` component. If several containers mount the same volume name then they will reuse the same volume and will be able to access to the same files.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "The path in the component container where the volume should be mounted. If not path is mentioned, default path is the is `/\u003cname\u003e`.", - "type": "string" - } - }, - "additionalProperties": false - } - } - }, - "additionalProperties": false - }, - "kubernetes": { - "description": "Allows importing into the devworkspace the Kubernetes resources defined in a given manifest. For example this allows reusing the Kubernetes definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "name": { - "description": "Mandatory name that allows referencing the component from other elements (such as commands) or from an external devfile that may reference this component through a parent or a plugin.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "openshift": { - "description": "Allows importing into the devworkspace the OpenShift resources defined in a given manifest. For example this allows reusing the OpenShift definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "volume": { - "description": "Allows specifying the definition of a volume shared by several other components", - "type": "object", - "properties": { - "ephemeral": { - "description": "Ephemeral volumes are not stored persistently across restarts. Defaults to false", - "type": "boolean" - }, - "size": { - "description": "Size of the volume", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "id": { - "description": "Id in a registry that contains a Devfile yaml file", - "type": "string" - }, - "kubernetes": { - "description": "Reference to a Kubernetes CRD of type DevWorkspaceTemplate", - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string" - } - }, - "additionalProperties": false - }, - "registryUrl": { - "type": "string" - }, - "uri": { - "description": "Uri of a Devfile yaml file", - "type": "string" - } - }, - "additionalProperties": false - }, "volume": { "description": "Allows specifying the definition of a volume shared by several other components", "type": "object", From 6471455677b28b0e892adc4c24e14acfc17678a4 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Thu, 8 Apr 2021 15:12:07 -0400 Subject: [PATCH 06/12] addressed doc review --- .../assembly_migrating-to-devfile-v2.adoc | 2 +- .../partials/proc_adding-event-bindings.adoc | 16 +---- .../partials/proc_migrating-commands.adoc | 4 +- .../partials/proc_migrating-components.adoc | 62 +++---------------- .../partials/proc_migrating-plug-ins.adoc | 6 +- .../partials/proc_migrating-projects.adoc | 5 +- .../proc_migrating-schema-version.adoc | 3 +- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 16 ++--- 8 files changed, 27 insertions(+), 87 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index b389551f..a7bf97d3 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -24,7 +24,7 @@ This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: +Go to the following GitHub issues: * link:https://github.com/devfile/api/issues/10[Devfile schema] * link:https://github.com/devfile/api/issues/31[Plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 814a577a..c023cc78 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,15 +2,7 @@ = Adding event bindings [role="_abstract"] -<<<<<<< HEAD -Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. -======= This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. ->>>>>>> d8b8834... more tweaks for consistent devfile versioning - -.Prerequisites - -Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. .Procedure @@ -50,11 +42,5 @@ events: + [role="_additional-resources"] .Additional resources -<<<<<<< HEAD -* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. -======= - -For a deeper understanding of adding events, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 850639d8..1e8a3323 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,7 +2,7 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to devfiles v2.x. The command section of devfile v2.x has major changes. A command specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate commands to devfiles v2.x. Major changes have been made from devfiles v1.x to the command section of devfile v2.x. A command specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -18,7 +18,7 @@ This section describes how to migrate commands to devfiles v2.x. The command sec [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating commands, go to the GitHub issues on the following topics: +Go to the following GitHub issues: * link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index a45e0737..c68abed2 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,23 +2,14 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to devfiles v2.x. The components section of devfiles v2.x has major changes. A component specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate components to devfiles v2.x. Major changes have been made from devfiles v1.x to the components section in devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure -<<<<<<< HEAD -<<<<<<< HEAD . Component is a polymorphic type + -For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +For a better syntax, the validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + -======= -. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. -======= -. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. ->>>>>>> d8b8834... more tweaks for consistent devfile versioning -+ ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] ---- v2.0 @@ -34,53 +25,18 @@ components: - kubernetes: uri: https://.../mongo.yaml ---- -<<<<<<< HEAD + -See https://github.com/devfile/api/issues/4[corresponding issue]. - -. Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. - -. Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. - -. Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. - -. Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. -. Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. - -. Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. - -. Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. - - -======= -+ ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +Go to the following GitHub issues: -<<<<<<< HEAD -<<<<<<< HEAD -* Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. -* Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. -* Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. -* Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. -* Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. -* Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. -* Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. -* Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. -======= -* link:https://github.com/devfile/api/issues/4[Component is a polymophic type] -======= -* link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] ->>>>>>> d8b8834... more tweaks for consistent devfile versioning +* link:https://github.com/devfile/api/issues/4[Polymorphic component type] * link:https://github.com/devfile/api/issues/19[Shared volumes across components] -* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/devfile/api/issues/48[Out of main pod containers] * link:https://github.com/devfile/api/issues/9[Replace alias with name] -* link:https://github.com/devfile/api/issues/8[Renaming dockerimage component type] -* link:https://github.com/devfile/api/issues/17[Specify sources path for containers] -* link:https://github.com/devfile/api/issues/14[Specify size of volume for component] -* link:https://github.com/devfile/api/issues/33[Containers endpoints: routes and ingresses] ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide +* link:https://github.com/devfile/api/issues/8[Rename dockerimage component type] +* link:https://github.com/devfile/api/issues/17[Specify source path for containers] +* link:https://github.com/devfile/api/issues/14[Specify size of volume for components] +* link:https://github.com/devfile/api/issues/27[Container endpoints: routes and ingresses] diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index b2e65115..b8525c56 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,7 +2,7 @@ = Migrating plug-ins [role="_abstract"] -This section describes how to migrate plug-ins to devfiles v2.x. The plug-ins section of devfile v2.x has major changes. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate plug-ins to devfiles v2.x. Major changes have been made from devfile v1.x to the plug-ins section of devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -79,6 +79,4 @@ components: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating plug-ins, go to the GitHub issue on the following topic: - -* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 6d7d3d62..f9f01847 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -6,7 +6,7 @@ This section describes how to migrate projects to devfiles v2.x. A project speci .Procedure -A major change in devfiles v2.x is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. + Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in the interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository. .starterProjects and projects description @@ -25,6 +25,5 @@ starterProjects: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating projects, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/42[StarterProjects] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 3b07374c..53611cfc 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -33,6 +33,5 @@ metadata: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating schema versions, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/7[SchemaVersion attribute] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute]. diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 2d3574e3..a33c2f9c 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -2,25 +2,27 @@ = Refering to a parent devfile in a devfile [role="_abstract"] +You can designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent. + .Prerequisites * xref:adding-schema-version-to-a-devfile.adoc[] * xref:adding-a-name-to-a-devfile.adoc[] -This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. +This section describes how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. .Procedure You can refer to a parent devfile in three different ways: -. registry -. uri -. kubernetes +* registry +* uri +* kubernetes .Parent referred by registry ==== -Using its `id` if it has been published in a registry. +Use the `id` if it has been published in a registry. [source,yaml] ---- @@ -35,7 +37,7 @@ parent: .Parent referred by uri ==== -Using the URI if it has been published on a static http server (like gist or pastebin). +Use the URI if it has been published on a static http server like gist or pastebin. [source,yaml] ---- @@ -54,7 +56,7 @@ parent: .Parent identified by a Kubernetes resource ==== -Using a Kubernetes resource name and namespace if it has been deployed on a Kubernete cluster. +Use a Kubernetes resource name and namespace if it has been deployed on a Kubernetes cluster. [source,yaml] ---- From f5c22d3e8e185443b3c6f114b4706d10c33bc5bc Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Thu, 28 Jan 2021 15:14:21 -0500 Subject: [PATCH 07/12] made migrating docs adhere to style guide --- .../assembly_migrating-to-devfile-v2.adoc | 7 ++- .../partials/proc_adding-event-bindings.adoc | 44 ++++++++++++++++--- .../partials/proc_migrating-commands.adoc | 32 +++++--------- .../partials/proc_migrating-components.adoc | 24 +++++++++- .../partials/proc_migrating-plug-ins.adoc | 18 ++++---- .../partials/proc_migrating-projects.adoc | 10 ++--- .../proc_migrating-schema-version.adoc | 8 ++-- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 20 ++++++--- 8 files changed, 104 insertions(+), 59 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index 00ff2030..f2e73f41 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -11,7 +11,7 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing v1.0 devfile to v2.0. +This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -24,10 +24,9 @@ This guide explains how to migrate an existing v1.0 devfile to v2.0. [role="_additional-resources"] .Additional resources -* New metadata: `version`. See link:https://github.com/che-incubator/devworkspace-api/issues/10[corresponding issue]. -* New mandatory metadata for plugins. See link:https://github.com/devfile/api/issues/31[corresponding issue]. +* New metadata: `version`, go to its link:https://github.com/che-incubator/devworkspace-api/issues/10[GitHub issue]. +* New mandatory metadata for plugins, go to its link:https://github.com/devfile/api/issues/31[GitHub issue]. ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] ifndef::parent-context-of-assembly_migrating-to-devfile-v2[:!context:] - diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index a013f442..4644112b 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,21 +2,22 @@ = Adding event bindings [role="_abstract"] +<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. +======= +This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. +>>>>>>> 0a125b6... made migrating docs adhere to style guide -.Prerequisites +Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. - - -.Procedure - -. Add an `events` section in the devfile, containing a list of `preStart` and `postStart` commands. +For an example, see the following yaml: ==== [source,yaml] ---- # v2.0 --- +<<<<<<< HEAD commands: - id: init-project apply: @@ -36,6 +37,33 @@ commands: commands: - copy-artifacts - init-cache +======= +components: + - container: + name: "copier" + image: '' + - container: + name: "maven" + image: '' + - plugin: + id: theia +Commands: +containerBuild: +reference: +composite: + + - exec: + name: "copyNeededFiles" + component: "copier" + commandLine: "cp somefile" + - exec: + name: "buildAll" + component: "maven" + commandLine: "mvn ..." + - vsCodeTask: + name: "openFile" + component: "theia" +>>>>>>> 0a125b6... made migrating docs adhere to style guide events: preStart: - init-project @@ -46,4 +74,8 @@ events: [role="_additional-resources"] .Additional resources +<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. +======= +To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. +>>>>>>> 0a125b6... made migrating docs adhere to style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 6339fc16..4d276c1a 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,33 +2,25 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate plug-ins to devfile v2. There ARE major changes in the `commands` section of the devfile. A command specified in a v1.0 devfile will NOT work as it is in a devfile v2.0. - -.Procedure - -. Command Groups: build,run,test,debug. -. Apply Command. -. Environment Varibables for a Specific Command. -. Renaming workdir into workingDir. -. Id and label for Composite Commands. -. Run exec Commands as Specific User. -. Devfile metadata: add a link to an external website. -. Stack/Devfile Matching Rules. +This section describes how to migrate commands to v2.0 devfiles. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. [role="_additional-resources"] .Additional resources -* Command Groups: build,run,test,debug. See https://github.com/che-incubator/devworkspace-api/issues/27[corresponding issue]. -* Apply Command. See https://github.com/devfile/api/issues/56[corresponding issue]. +To learn more about commands in v2.0 devfiles, go to the commands' GitHub issues on the following topics: + +* link:https://github.com/che-incubator/devworkspace-api/issues/27[Command groups: build,run,test,debug] + +* link:https://github.com/devfile/api/issues/56[Apply command] -* Environment Varibables for a Specific Command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/21[Environment varibables for a specific command] -* Renaming workdir into workingDir. See https://github.com/che-incubator/devworkspace-api/issues/22[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/22[Renaming workdir into workingDir] -* Id and label for Composite Commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/18[Id and label for composite commands] -* Run exec Commands as Specific User. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/34[Run exec commands as specific user] -* Devfile metadata: add a link to an external website. See https://github.com/che-incubator/devworkspace-api/issues/38[corresponding issue]. +* link:https://github.com/che-incubator/devworkspace-api/issues/38[Devfile metadata: add a link to an external website] -* Stack/Devfile Matching Rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue]. \ No newline at end of file +* link:https://github.com/che-incubator/devworkspace-api/issues/40[Stack/devfile matching rules] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index fc886947..018cfe20 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,14 +2,19 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to devfile v2. There ARE major changes in the `components` section of the devfile. A component specified in a v1.0 devfile will NOT work as it is in a devfile v2.0. +This section describes how to migrate components to v2.0 devfiles. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. -.Procedure +To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +For an example, see the following yaml: + +<<<<<<< HEAD . Component is a polymorphic type + For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + +======= +>>>>>>> 0a125b6... made migrating docs adhere to style guide [source,yaml] ---- v2.0 @@ -25,6 +30,7 @@ components: - kubernetes: uri: https://.../mongo.yaml ---- +<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -42,11 +48,15 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. . Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. +======= +>>>>>>> 0a125b6... made migrating docs adhere to style guide [role="_additional-resources"] .Additional resources +To learn more about components in v2.0 devfiles, go to the components' GitHub issues on the following topics: +<<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. * Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. * Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. @@ -55,3 +65,13 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. * Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. * Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. * Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. +======= +* link:https://github.com/che-incubator/devworkspace-api/issues/4[Component is a polymophic type] +* link:https://github.com/che-incubator/devworkspace-api/issues/19[Shared volumes across components] +* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/che-incubator/devworkspace-api/issues/9[Replace alias with name] +* link:https://github.com/che-incubator/devworkspace-api/issues/8[Renaming dockerimage component type] +* link:https://github.com/che-incubator/devworkspace-api/issues/17[Specify sources path for containers] +* link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] +* link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] +>>>>>>> 0a125b6... made migrating docs adhere to style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 97e170a4..3a08a2b0 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -1,12 +1,10 @@ [id="proc_migrating-plug-ins_{context}"] -= Migrating plug-ins += Migrating plugins [role="_abstract"] -This section describes how to migrate plug-ins to devfile v2. There ARE major changes about the definition of plugins in a devfile. Plugins are now specified using a devfile. A plugin specified in a v1.0 meta.yaml will NOT work as it is in a devfile v2.0. +This section describes how to migrate plugins to v2.0 devfiles. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. Instead, specify a plugins using a devfile. -.Procedure - -. Plugins are now specified using a devfile. A plugin specified in a v1.0 meta.yaml will NOT work as it is in a devfile v2.0. +For an example of the new plugins, see the following yaml: [source,yaml] ---- @@ -28,9 +26,9 @@ metadata: firstPublicationDate: "2020-02-20" pluginType: che-theia-vsx # <== mandatory # for plugins - # Valid types: + # Valid types: # che-theia-vsx - # che-editor, + # che-editor, # che-theia-plugin, # che-theia-ext, # generic-service, @@ -58,7 +56,7 @@ components: name: m2 ---- -. And then can be referenced from a distinct devfile: +To reference a plugin from a distinct devfile, see the follow yaml: [source,yaml] ---- @@ -70,11 +68,11 @@ components: - plugin: name: java language server id: redhat/java11/0.57.0 # other then by `id`, a plugin - # can be referenced by `uri` and + # can be referenced by `uri` and # `kubernetes` ---- [role="_additional-resources"] .Additional resources -* See https://github.com/che-incubator/devworkspace-api/issues/31[corresponding issue]. +To learn more about plugins in v2.0 devfiles, go to the plugins' link:https://github.com/che-incubator/devworkspace-api/issues/31[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index e6616ef6..3031763b 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -2,12 +2,10 @@ = Migrating projects [role="_abstract"] -There are NO major changes in the `projects` section of the devfile. A project specified in a v1.0 devfile will work as it is in a devfile v2.0. +This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. -.Procedure +A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. -* The only major change is the addition of a new kind of project: `starterProjects`. Those are supposed to be used in interactive mode only (user pick one) and the git repo get not be cloned but only source code get copied (kind of what `git archive --remote= | tar -t` would do). -+ .starterProjects and projects description ==== [source,yaml] @@ -18,10 +16,10 @@ starterProjects: - name: "kafka-project" description: "Use this app to get a nodejs application for working with kafka" - name: "simple-project" - description: "Use this app to get a simple "hello world" nodejs application" + description: "Use this app to get a simple 'hello world' nodejs application" ---- ==== [role="_additional-resources"] .Additional resources -* See link:https://github.com/che-incubator/devworkspace-api/issues/42[corresponding issue]. +To learn more about starterProjects in v2.0 devfiles, go to starterProjects' link:https://github.com/che-incubator/devworkspace-api/issues/42[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index cf8d7dc2..6b97bb46 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -2,11 +2,11 @@ = Migrating schema version [role="_abstract"] -This section describes how to migrate schema version. +This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. -.Procedure +To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. -* Replace `apiVersion: 1.0.0` by `schemaVersion: 2.0.0`: +For an example, see the following yaml: [cols="1a,1a"] |==== @@ -34,4 +34,4 @@ metadata: [role="_additional-resources"] .Additional resources -* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue] +To learn more about the schema version in v2.0 devfiles, go to schema version's link:https://github.com/che-incubator/devworkspace-api/issues/7[GitHub issue]. diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 961f590d..8f1d8c3c 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -2,18 +2,24 @@ = Refering to a parent devfile in a devfile [role="_abstract"] -It is possible to refer to another devfile as a parent to a given devfile. If a parent is specified, the devfile will inherit all behaviour from the parent. Part of the content of the parent can be overridden in the child devfile. That allows refering a devfile (the parent) from a distinct devfile and makes it possible to reuse in multiple devfiles the same parent (the stack). - .Prerequisites * xref:adding-schema-version-to-a-devfile.adoc[] * xref:adding-a-name-to-a-devfile.adoc[] -.Procedure +This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. + + + +You can refer to a parent devfile in three different ways: + +* registry + +* uri + +* kubernetes -* A parent devfile can be referenced in 3 different ways: `registry`, `uri` or `kubernetes`. -+ .Parent referred by registry ==== Using its `id` if it has been published in a registry. @@ -28,7 +34,7 @@ parent: registry: https://devfile-registry.io/ ---- ==== -+ + .Parent referred by uri ==== Using the URI if it has been published on a static http server (like gist or pastebin). @@ -42,7 +48,7 @@ parent: uri: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml ---- ==== -+ + .Parent identified by a Kubernetes resource ==== Using a Kubernetes resource name and namespace if it has been deployed on a Kubernete cluster. From 155d6ec472902d66c8d4d4fe3792af7461cb3684 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Fri, 12 Mar 2021 11:55:26 -0500 Subject: [PATCH 08/12] brought back the procedures, updated links, more changes to content for consistency and style guide --- .../assembly_migrating-to-devfile-v2.adoc | 6 ++-- .../partials/proc_adding-event-bindings.adoc | 15 ++++++++-- .../partials/proc_migrating-commands.adoc | 29 +++++++++++++------ .../partials/proc_migrating-components.adoc | 28 ++++++++++++++---- .../partials/proc_migrating-plug-ins.adoc | 20 ++++++++----- .../partials/proc_migrating-projects.adoc | 7 ++++- .../proc_migrating-schema-version.adoc | 13 +++++---- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 15 ++++++---- 8 files changed, 95 insertions(+), 38 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index f2e73f41..2cfcb66c 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -24,8 +24,10 @@ This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. [role="_additional-resources"] .Additional resources -* New metadata: `version`, go to its link:https://github.com/che-incubator/devworkspace-api/issues/10[GitHub issue]. -* New mandatory metadata for plugins, go to its link:https://github.com/devfile/api/issues/31[GitHub issue]. +For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: + +* link:https://github.com/devfile/api/issues/10[Devfile schema] +* link:https://github.com/devfile/api/issues/31[Plugin mechanism] ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 4644112b..867db51c 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -8,10 +8,14 @@ Commands can be bound to events to form four different types of events: `preStar This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. >>>>>>> 0a125b6... made migrating docs adhere to style guide +.Prerequisites + Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. -For an example, see the following yaml: +.Procedure +. Add an `events` section in the devfile, containing a list of `preStart` and `postStart` commands. ++ ==== [source,yaml] ---- @@ -71,11 +75,18 @@ events: - pre-compile-cmd ---- ==== - ++ [role="_additional-resources"] .Additional resources <<<<<<< HEAD +<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. ======= To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= + +For a deeper understanding of adding events, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 4d276c1a..0b9ce134 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,25 +2,36 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to v2.0 devfiles. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate commands to v2.0 devfiles. The command section of v2.0 devfile has major changes. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. + +.Procedure + +. Command groups: build, run, test, debug. +. Apply command. +. Environment variables for a specific command. +. Renaming workdir into workingDir. +. Id and label for composite commands. +. Run exec commands as specific user. +. Devfile metadata: add a link to an external website. +. Stack or devfile matching rules. [role="_additional-resources"] .Additional resources -To learn more about commands in v2.0 devfiles, go to the commands' GitHub issues on the following topics: +For a deeper understanding of migrating commands, go to the GitHub issues on the following topics: -* link:https://github.com/che-incubator/devworkspace-api/issues/27[Command groups: build,run,test,debug] +* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] * link:https://github.com/devfile/api/issues/56[Apply command] -* link:https://github.com/che-incubator/devworkspace-api/issues/21[Environment varibables for a specific command] +* link:https://github.com/devfile/api/issues/21[Environment variables for a specific command] -* link:https://github.com/che-incubator/devworkspace-api/issues/22[Renaming workdir into workingDir] +* link:https://github.com/devfile/api/issues/22[Renaming workdir into workingDir] -* link:https://github.com/che-incubator/devworkspace-api/issues/18[Id and label for composite commands] +* link:https://github.com/devfile/api/issues/18[Id and label for composite commands] -* link:https://github.com/che-incubator/devworkspace-api/issues/34[Run exec commands as specific user] +* link:https://github.com/devfile/api/issues/34[Run exec commands as specific user] -* link:https://github.com/che-incubator/devworkspace-api/issues/38[Devfile metadata: add a link to an external website] +* link:https://github.com/devfile/api/issues/38[Devfile metadata: add a link to an external website] -* link:https://github.com/che-incubator/devworkspace-api/issues/40[Stack/devfile matching rules] +* link:https://github.com/devfile/api/issues/40[Stack or devfile matching rules] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index 018cfe20..1473e06a 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,12 +2,11 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to v2.0 devfiles. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate components to v2.0 devfiles. The components section of v2.0 devfile has major changes. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. -To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. - -For an example, see the following yaml: +.Procedure +<<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type + @@ -15,6 +14,10 @@ For a better syntax validation component now is defined as a polymorphic type an + ======= >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. ++ +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] ---- v2.0 @@ -31,6 +34,7 @@ components: uri: https://.../mongo.yaml ---- <<<<<<< HEAD +<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -51,11 +55,15 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. ======= >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= ++ +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [role="_additional-resources"] .Additional resources -To learn more about components in v2.0 devfiles, go to the components' GitHub issues on the following topics: +For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +<<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. * Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. @@ -75,3 +83,13 @@ To learn more about components in v2.0 devfiles, go to the components' GitHub is * link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] * link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +* link:https://github.com/devfile/api/issues/4[Component is a polymophic type] +* link:https://github.com/devfile/api/issues/19[Shared volumes across components] +* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/devfile/api/issues/9[Replace alias with name] +* link:https://github.com/devfile/api/issues/8[Renaming dockerimage component type] +* link:https://github.com/devfile/api/issues/17[Specify sources path for containers] +* link:https://github.com/devfile/api/issues/14[Specify size of volume for component] +* link:https://github.com/devfile/api/issues/33[Containers endpoints: routes and ingresses] +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 3a08a2b0..5c24a539 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,10 +2,13 @@ = Migrating plugins [role="_abstract"] -This section describes how to migrate plugins to v2.0 devfiles. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. Instead, specify a plugins using a devfile. +This section describes how to migrate plugins to v2.0 devfiles. The plugins section of v2.0 devfile has major changes. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. -For an example of the new plugins, see the following yaml: +.Procedure +. Specify a plugin using a devfile. + ++ [source,yaml] ---- v2.0 @@ -55,9 +58,9 @@ components: - volume: name: m2 ---- - -To reference a plugin from a distinct devfile, see the follow yaml: - ++ +. Reference a plugin from a distinct devfile. ++ [source,yaml] ---- v2.0 @@ -71,8 +74,11 @@ components: # can be referenced by `uri` and # `kubernetes` ---- - ++ [role="_additional-resources"] .Additional resources -To learn more about plugins in v2.0 devfiles, go to the plugins' link:https://github.com/che-incubator/devworkspace-api/issues/31[GitHub issue]. + +For a deeper understanding of migrating plugins, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/31[Plugin mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 3031763b..6e61e7fb 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -4,9 +4,12 @@ [role="_abstract"] This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. +.Procedure + A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. .starterProjects and projects description + ==== [source,yaml] ---- @@ -22,4 +25,6 @@ starterProjects: [role="_additional-resources"] .Additional resources -To learn more about starterProjects in v2.0 devfiles, go to starterProjects' link:https://github.com/che-incubator/devworkspace-api/issues/42[GitHub issue]. +For a deeper understanding of migrating projects, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/42[StarterProjects] diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 6b97bb46..b1034f06 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -4,10 +4,10 @@ [role="_abstract"] This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. -To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. - -For an example, see the following yaml: +.Procedure +. To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. ++ [cols="1a,1a"] |==== | @@ -29,9 +29,10 @@ metadata: name: devfile-sample ---- |==== - - ++ [role="_additional-resources"] .Additional resources -To learn more about the schema version in v2.0 devfiles, go to schema version's link:https://github.com/che-incubator/devworkspace-api/issues/7[GitHub issue]. +For a deeper understanding of migrating schema versions, go to the GitHub issue on the following topic: + +* link:https://github.com/devfile/api/issues/7[SchemaVersion attribute] diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 8f1d8c3c..2d3574e3 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -10,15 +10,13 @@ This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. - +.Procedure You can refer to a parent devfile in three different ways: -* registry - -* uri - -* kubernetes +. registry +. uri +. kubernetes .Parent referred by registry ==== @@ -45,7 +43,12 @@ schemaVersion: 2.0.0 metadata: name: my-project-dev parent: +<<<<<<< HEAD uri: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml +======= + id: redhat/nodejs/11.6 + uri: https://raw.githubusercontent.com/devfile/registry/master/stacks/nodejs/devfile.yaml +>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide ---- ==== From 1a06eb09db108c1a9cfa52a1cec060a55983ff03 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Mon, 29 Mar 2021 11:12:38 -0400 Subject: [PATCH 09/12] more tweaks for consistent devfile versioning --- .../assembly_migrating-to-devfile-v2.adoc | 4 ++-- .../partials/proc_adding-event-bindings.adoc | 4 ++++ .../partials/proc_migrating-commands.adoc | 2 +- .../partials/proc_migrating-components.adoc | 10 ++++++++- .../partials/proc_migrating-plug-ins.adoc | 22 +++++++++---------- .../partials/proc_migrating-projects.adoc | 4 ++-- .../proc_migrating-schema-version.adoc | 4 ++-- 7 files changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index 2cfcb66c..b389551f 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -11,7 +11,7 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. +This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -27,7 +27,7 @@ This guide explains how to migrate an existing v1.0 devfile to a v2.0 devfile. For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: * link:https://github.com/devfile/api/issues/10[Devfile schema] -* link:https://github.com/devfile/api/issues/31[Plugin mechanism] +* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 867db51c..97545f35 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -3,10 +3,14 @@ [role="_abstract"] <<<<<<< HEAD +<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. ======= This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. >>>>>>> 0a125b6... made migrating docs adhere to style guide +======= +This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. +>>>>>>> d8b8834... more tweaks for consistent devfile versioning .Prerequisites diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 0b9ce134..850639d8 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,7 +2,7 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to v2.0 devfiles. The command section of v2.0 devfile has major changes. A command specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate commands to devfiles v2.x. The command section of devfile v2.x has major changes. A command specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index 1473e06a..c41624e0 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,10 +2,11 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to v2.0 devfiles. The components section of v2.0 devfile has major changes. A component specified in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate components to devfiles v2.x. The components section of devfiles v2.x has major changes. A component specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure +<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type @@ -16,6 +17,9 @@ For a better syntax validation component now is defined as a polymorphic type an >>>>>>> 0a125b6... made migrating docs adhere to style guide ======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +======= +. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. +>>>>>>> d8b8834... more tweaks for consistent devfile versioning + >>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] @@ -63,6 +67,7 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -85,6 +90,9 @@ For a deeper understanding of migrating components, go to the GitHub issues on t >>>>>>> 0a125b6... made migrating docs adhere to style guide ======= * link:https://github.com/devfile/api/issues/4[Component is a polymophic type] +======= +* link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] +>>>>>>> d8b8834... more tweaks for consistent devfile versioning * link:https://github.com/devfile/api/issues/19[Shared volumes across components] * link:https://github.com/devfile/api/issues/48[Out of main pod components] * link:https://github.com/devfile/api/issues/9[Replace alias with name] diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index 5c24a539..b2e65115 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -1,12 +1,12 @@ [id="proc_migrating-plug-ins_{context}"] -= Migrating plugins += Migrating plug-ins [role="_abstract"] -This section describes how to migrate plugins to v2.0 devfiles. The plugins section of v2.0 devfile has major changes. A plugin specified in a meta.yaml in a v1.0 devfile no longer works in a v2.0 devfile. +This section describes how to migrate plug-ins to devfiles v2.x. The plug-ins section of devfile v2.x has major changes. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. .Procedure -. Specify a plugin using a devfile. +. Specify a plug-in using a devfile. + [source,yaml] @@ -27,12 +27,12 @@ metadata: repository: https://github.../vscode-java category: Language firstPublicationDate: "2020-02-20" - pluginType: che-theia-vsx # <== mandatory - # for plugins + plug-inType: che-theia-vsx # <== mandatory + # for plug-ins # Valid types: # che-theia-vsx # che-editor, - # che-theia-plugin, + # che-theia-plug-in, # che-theia-ext, # generic-service, # generic-ui @@ -59,7 +59,7 @@ components: name: m2 ---- + -. Reference a plugin from a distinct devfile. +. Reference a plug-in from a distinct devfile. + [source,yaml] ---- @@ -68,9 +68,9 @@ v2.0 devfile.yaml --- components: -- plugin: +- plug-in: name: java language server - id: redhat/java11/0.57.0 # other then by `id`, a plugin + id: redhat/java11/0.57.0 # other then by `id`, a plug-in # can be referenced by `uri` and # `kubernetes` ---- @@ -79,6 +79,6 @@ components: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating plugins, go to the GitHub issue on the following topic: +For a deeper understanding of migrating plug-ins, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/31[Plugin mechanism] +* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 6e61e7fb..6d7d3d62 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -2,11 +2,11 @@ = Migrating projects [role="_abstract"] -This section describes how to migrate projects to v2.0 devfiles. A project specified in a v1.0 devfile still works in a v2.0 devfile. +This section describes how to migrate projects to devfiles v2.x. A project specified in a devfile v1.x still works in a devfile v2.x. .Procedure -A major change in v2.0 devfile is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. +A major change in devfiles v2.x is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. .starterProjects and projects description diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index b1034f06..3b07374c 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -2,11 +2,11 @@ = Migrating schema version [role="_abstract"] -This section describes how to migrate a schema version to v2.0 devfiles. A schema version specified in a v1.0 devfile still works in a v2.0 devfile. +This section describes how to migrate a schema version to devfiles v2.x. A schema version specified in a devfile v1.x still works in a devfile v2.x. .Procedure -. To migrate a schema version from v1.0 devfiles to v2.0 devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. +. To migrate a schema version from devfiles v1.x to devfiles v2.x, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`. + [cols="1a,1a"] |==== From fbfe3495ca264dc796e4e42a5372b3978e238dae Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Tue, 6 Apr 2021 15:38:24 -0400 Subject: [PATCH 10/12] fixed merge conflicts --- .../partials/proc_adding-event-bindings.adoc | 36 ------------------- .../partials/proc_migrating-components.adoc | 17 --------- 2 files changed, 53 deletions(-) diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 97545f35..814a577a 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -3,12 +3,8 @@ [role="_abstract"] <<<<<<< HEAD -<<<<<<< HEAD Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. ======= -This section describes how to add an event to v2.0 devfiles. An event specified in a v1.0 devfile still works in a v2.0 devfile. ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. >>>>>>> d8b8834... more tweaks for consistent devfile versioning @@ -25,7 +21,6 @@ Add an `events` section in your devfile and make sure it contains a list of `pre ---- # v2.0 --- -<<<<<<< HEAD commands: - id: init-project apply: @@ -45,33 +40,6 @@ commands: commands: - copy-artifacts - init-cache -======= -components: - - container: - name: "copier" - image: '' - - container: - name: "maven" - image: '' - - plugin: - id: theia -Commands: -containerBuild: -reference: -composite: - - - exec: - name: "copyNeededFiles" - component: "copier" - commandLine: "cp somefile" - - exec: - name: "buildAll" - component: "maven" - commandLine: "mvn ..." - - vsCodeTask: - name: "openFile" - component: "theia" ->>>>>>> 0a125b6... made migrating docs adhere to style guide events: preStart: - init-project @@ -83,12 +51,8 @@ events: [role="_additional-resources"] .Additional resources <<<<<<< HEAD -<<<<<<< HEAD * See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. ======= -To learn more about events in v2.0 devfiles, go to the events' link:https://github.com/che-incubator/devworkspace-api/issues/32[GitHub issue]. ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= For a deeper understanding of adding events, go to the GitHub issue on the following topic: diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index c41624e0..a45e0737 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -6,7 +6,6 @@ This section describes how to migrate components to devfiles v2.x. The component .Procedure -<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD . Component is a polymorphic type @@ -14,8 +13,6 @@ This section describes how to migrate components to devfiles v2.x. The component For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + ======= ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. ======= . To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. @@ -38,7 +35,6 @@ components: uri: https://.../mongo.yaml ---- <<<<<<< HEAD -<<<<<<< HEAD + See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -56,8 +52,6 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. . Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. -======= ->>>>>>> 0a125b6... made migrating docs adhere to style guide ======= + @@ -67,7 +61,6 @@ See https://github.com/devfile/api/issues/4[corresponding issue]. For a deeper understanding of migrating components, go to the GitHub issues on the following topics: -<<<<<<< HEAD <<<<<<< HEAD <<<<<<< HEAD * Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. @@ -79,16 +72,6 @@ For a deeper understanding of migrating components, go to the GitHub issues on t * Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. * Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. ======= -* link:https://github.com/che-incubator/devworkspace-api/issues/4[Component is a polymophic type] -* link:https://github.com/che-incubator/devworkspace-api/issues/19[Shared volumes across components] -* link:https://github.com/devfile/api/issues/48[Out of main pod components] -* link:https://github.com/che-incubator/devworkspace-api/issues/9[Replace alias with name] -* link:https://github.com/che-incubator/devworkspace-api/issues/8[Renaming dockerimage component type] -* link:https://github.com/che-incubator/devworkspace-api/issues/17[Specify sources path for containers] -* link:https://github.com/che-incubator/devworkspace-api/issues/14[Specify size of volume for component] -* link:https://github.com/che-incubator/devworkspace-api/issues/33[Containers endpoints: routes and ingresses] ->>>>>>> 0a125b6... made migrating docs adhere to style guide -======= * link:https://github.com/devfile/api/issues/4[Component is a polymophic type] ======= * link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] From d1d03efa2830428e2a17b9da0074fda2a63c4786 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Thu, 8 Apr 2021 15:12:07 -0400 Subject: [PATCH 11/12] addressed doc review --- .../assembly_migrating-to-devfile-v2.adoc | 2 +- .../partials/proc_adding-event-bindings.adoc | 16 +---- .../partials/proc_migrating-commands.adoc | 4 +- .../partials/proc_migrating-components.adoc | 62 +++---------------- .../partials/proc_migrating-plug-ins.adoc | 6 +- .../partials/proc_migrating-projects.adoc | 5 +- .../proc_migrating-schema-version.adoc | 3 +- ...ring-to-a-parent-devfile-in-a-devfile.adoc | 16 ++--- 8 files changed, 27 insertions(+), 87 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index b389551f..a7bf97d3 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -24,7 +24,7 @@ This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics: +Go to the following GitHub issues: * link:https://github.com/devfile/api/issues/10[Devfile schema] * link:https://github.com/devfile/api/issues/31[Plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index 814a577a..c023cc78 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,15 +2,7 @@ = Adding event bindings [role="_abstract"] -<<<<<<< HEAD -Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. -======= This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x. ->>>>>>> d8b8834... more tweaks for consistent devfile versioning - -.Prerequisites - -Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands. .Procedure @@ -50,11 +42,5 @@ events: + [role="_additional-resources"] .Additional resources -<<<<<<< HEAD -* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. -======= - -For a deeper understanding of adding events, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 850639d8..1e8a3323 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,7 +2,7 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to devfiles v2.x. The command section of devfile v2.x has major changes. A command specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate commands to devfiles v2.x. Major changes have been made from devfiles v1.x to the command section of devfile v2.x. A command specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -18,7 +18,7 @@ This section describes how to migrate commands to devfiles v2.x. The command sec [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating commands, go to the GitHub issues on the following topics: +Go to the following GitHub issues: * link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index a45e0737..c68abed2 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,23 +2,14 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to devfiles v2.x. The components section of devfiles v2.x has major changes. A component specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate components to devfiles v2.x. Major changes have been made from devfiles v1.x to the components section in devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure -<<<<<<< HEAD -<<<<<<< HEAD . Component is a polymorphic type + -For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +For a better syntax, the validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + -======= -. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`. -======= -. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`. ->>>>>>> d8b8834... more tweaks for consistent devfile versioning -+ ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [source,yaml] ---- v2.0 @@ -34,53 +25,18 @@ components: - kubernetes: uri: https://.../mongo.yaml ---- -<<<<<<< HEAD + -See https://github.com/devfile/api/issues/4[corresponding issue]. - -. Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. - -. Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. - -. Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. - -. Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. -. Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. - -. Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. - -. Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue]. - - -======= -+ ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating components, go to the GitHub issues on the following topics: +Go to the following GitHub issues: -<<<<<<< HEAD -<<<<<<< HEAD -* Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue]. -* Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue]. -* Out of Main Pod Components. See https://github.com/devfile/api/issues/48[corresponding issue]. -* Replace Alias with Name. See https://github.com/devfile/api/issues/9[corresponding issue]. -* Renaming dockerimage component type. See https://github.com/devfile/api/issues/8[corresponding issue]. -* Specify sources path for containers. See https://github.com/devfile/api/issues/17[corresponding issue]. -* Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue]. -* Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue]. -======= -* link:https://github.com/devfile/api/issues/4[Component is a polymophic type] -======= -* link:https://github.com/devfile/api/issues/4[Component is a polymorphic type] ->>>>>>> d8b8834... more tweaks for consistent devfile versioning +* link:https://github.com/devfile/api/issues/4[Polymorphic component type] * link:https://github.com/devfile/api/issues/19[Shared volumes across components] -* link:https://github.com/devfile/api/issues/48[Out of main pod components] +* link:https://github.com/devfile/api/issues/48[Out of main pod containers] * link:https://github.com/devfile/api/issues/9[Replace alias with name] -* link:https://github.com/devfile/api/issues/8[Renaming dockerimage component type] -* link:https://github.com/devfile/api/issues/17[Specify sources path for containers] -* link:https://github.com/devfile/api/issues/14[Specify size of volume for component] -* link:https://github.com/devfile/api/issues/33[Containers endpoints: routes and ingresses] ->>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide +* link:https://github.com/devfile/api/issues/8[Rename dockerimage component type] +* link:https://github.com/devfile/api/issues/17[Specify source path for containers] +* link:https://github.com/devfile/api/issues/14[Specify size of volume for components] +* link:https://github.com/devfile/api/issues/27[Container endpoints: routes and ingresses] diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index b2e65115..b8525c56 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,7 +2,7 @@ = Migrating plug-ins [role="_abstract"] -This section describes how to migrate plug-ins to devfiles v2.x. The plug-ins section of devfile v2.x has major changes. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate plug-ins to devfiles v2.x. Major changes have been made from devfile v1.x to the plug-ins section of devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -79,6 +79,4 @@ components: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating plug-ins, go to the GitHub issue on the following topic: - -* link:https://github.com/devfile/api/issues/31[Plug-in mechanism] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index 6d7d3d62..f9f01847 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -6,7 +6,7 @@ This section describes how to migrate projects to devfiles v2.x. A project speci .Procedure -A major change in devfiles v2.x is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo. + Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in the interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository. .starterProjects and projects description @@ -25,6 +25,5 @@ starterProjects: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating projects, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/42[StarterProjects] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 3b07374c..53611cfc 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -33,6 +33,5 @@ metadata: [role="_additional-resources"] .Additional resources -For a deeper understanding of migrating schema versions, go to the GitHub issue on the following topic: -* link:https://github.com/devfile/api/issues/7[SchemaVersion attribute] +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute]. diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index 2d3574e3..a33c2f9c 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -2,25 +2,27 @@ = Refering to a parent devfile in a devfile [role="_abstract"] +You can designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent. + .Prerequisites * xref:adding-schema-version-to-a-devfile.adoc[] * xref:adding-a-name-to-a-devfile.adoc[] -This section teaches you how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. +This section describes how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. .Procedure You can refer to a parent devfile in three different ways: -. registry -. uri -. kubernetes +* registry +* uri +* kubernetes .Parent referred by registry ==== -Using its `id` if it has been published in a registry. +Use the `id` if it has been published in a registry. [source,yaml] ---- @@ -35,7 +37,7 @@ parent: .Parent referred by uri ==== -Using the URI if it has been published on a static http server (like gist or pastebin). +Use the URI if it has been published on a static http server like gist or pastebin. [source,yaml] ---- @@ -54,7 +56,7 @@ parent: .Parent identified by a Kubernetes resource ==== -Using a Kubernetes resource name and namespace if it has been deployed on a Kubernete cluster. +Use a Kubernetes resource name and namespace if it has been deployed on a Kubernetes cluster. [source,yaml] ---- From 5c5ec99ceb9207392c8c9497e8b18afc04bf8435 Mon Sep 17 00:00:00 2001 From: jc-berger <> Date: Fri, 9 Apr 2021 17:05:41 -0400 Subject: [PATCH 12/12] more doc changes --- .../partials/assembly_migrating-to-devfile-v2.adoc | 4 ++-- .../partials/proc_adding-event-bindings.adoc | 2 +- .../user-guide/partials/proc_migrating-commands.adoc | 4 ++-- .../partials/proc_migrating-components.adoc | 6 +++--- .../user-guide/partials/proc_migrating-plug-ins.adoc | 4 ++-- .../user-guide/partials/proc_migrating-projects.adoc | 4 ++-- .../partials/proc_migrating-schema-version.adoc | 2 +- ...roc_refering-to-a-parent-devfile-in-a-devfile.adoc | 11 +++++------ 8 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc index a7bf97d3..8a71db29 100644 --- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc +++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc @@ -11,7 +11,7 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. +The following documents explain how to migrate an existing devfile v1.x to a devfile v2.x: * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -24,7 +24,7 @@ This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. [role="_additional-resources"] .Additional resources -Go to the following GitHub issues: +For a deeper understanding of migrating devfiles, go to the following GitHub issues: * link:https://github.com/devfile/api/issues/10[Devfile schema] * link:https://github.com/devfile/api/issues/31[Plug-in mechanism] diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc index c023cc78..573e2279 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -43,4 +43,4 @@ events: [role="_additional-resources"] .Additional resources -Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] +For a deeper understanding of adding event bindings, go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands]. diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 1e8a3323..c2b23ecc 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,7 +2,7 @@ = Migrating commands [role="_abstract"] -This section describes how to migrate commands to devfiles v2.x. Major changes have been made from devfiles v1.x to the command section of devfile v2.x. A command specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate commands to devfiles v2.x. A command specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -18,7 +18,7 @@ This section describes how to migrate commands to devfiles v2.x. Major changes h [role="_additional-resources"] .Additional resources -Go to the following GitHub issues: +For a deeper understanding of migrating commands, go to the following GitHub issues: * link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc index c68abed2..62d92314 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,13 +2,13 @@ = Migrating components [role="_abstract"] -This section describes how to migrate components to devfiles v2.x. Major changes have been made from devfiles v1.x to the components section in devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate components to devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x. .Procedure . Component is a polymorphic type + -For a better syntax, the validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. +To get a better syntax validation, define a component as a polymorphic type and implement it as `container`, `kubernetes`, `openshift`, `plugin` or `volume`. + [source,yaml] ---- @@ -30,7 +30,7 @@ components: [role="_additional-resources"] .Additional resources -Go to the following GitHub issues: +For a deeper understanding of migrating components, go to the following GitHub issues: * link:https://github.com/devfile/api/issues/4[Polymorphic component type] * link:https://github.com/devfile/api/issues/19[Shared volumes across components] diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc index b8525c56..d93cc979 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,7 +2,7 @@ = Migrating plug-ins [role="_abstract"] -This section describes how to migrate plug-ins to devfiles v2.x. Major changes have been made from devfile v1.x to the plug-ins section of devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. +This section describes how to migrate plug-ins to devfiles v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x. .Procedure @@ -79,4 +79,4 @@ components: [role="_additional-resources"] .Additional resources -Go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism] +For a deeper understanding of migrating plug-ins, go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism]. diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc index f9f01847..f94e9d48 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -6,7 +6,7 @@ This section describes how to migrate projects to devfiles v2.x. A project speci .Procedure - Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in the interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository. + Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository. .starterProjects and projects description @@ -26,4 +26,4 @@ starterProjects: [role="_additional-resources"] .Additional resources -Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. +For a deeper understanding of migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc index 53611cfc..558ba1cc 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -34,4 +34,4 @@ metadata: [role="_additional-resources"] .Additional resources -Go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute]. +For a deeper understanding of migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute]. diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc index a33c2f9c..a0edf4fe 100644 --- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc +++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc @@ -2,15 +2,12 @@ = Refering to a parent devfile in a devfile [role="_abstract"] -You can designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent. +This section describes how to designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. .Prerequisites -* xref:adding-schema-version-to-a-devfile.adoc[] -* xref:adding-a-name-to-a-devfile.adoc[] - - -This section describes how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles. +* Define the schemaVersion to v2.x. If you need to define your schemaVersion, go to xref:adding-schema-version-to-a-devfile.adoc[]. +* Define a name for the devfile. If you need to define a name for your devfile go to xref:adding-a-name-to-a-devfile.adoc[]. .Procedure @@ -73,5 +70,7 @@ parent: [role="_additional-resources"] .Additional resources +For a deeper understanding of referring to parent devfiles, go to the following topics: + * xref:api-reference.adoc[] * xref:devfile-samples.adoc[]