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..75bb2dd5 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,11 @@ endif::[] :context: assembly_migrating-to-devfile-v2 -This guide explains how to migrate an existing v1.0 devfile to v2.0. +<<<<<<< HEAD +The following documents explain how to migrate an existing devfile v1.x to a devfile v2.x: +======= +This guide explains how to migrate an existing devfile v1.x to a devfile v2.x. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 * xref:migrating-schema-version.adoc[] * xref:migrating-projects.adoc[] @@ -24,10 +28,15 @@ 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]. +<<<<<<< HEAD +For a deeper understanding of migrating devfiles, go to the following GitHub issues: +======= +Go to the following GitHub issues: +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 + +* link:https://github.com/devfile/api/issues/10[Devfile schema] +* 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}] 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..ee05e9bf 100644 --- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc +++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc @@ -2,16 +2,12 @@ = Adding event bindings [role="_abstract"] -Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`. - -.Prerequisites - - +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. .Procedure . Add an `events` section in the devfile, containing a list of `preStart` and `postStart` commands. - ++ ==== [source,yaml] ---- @@ -43,7 +39,12 @@ events: - pre-compile-cmd ---- ==== - ++ [role="_additional-resources"] .Additional resources -* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue]. + +<<<<<<< HEAD +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]. +======= +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands] +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 6485d215..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 the `commands` section to devfile v2.x. A command specified in a v1.0 devfile does not work as it is 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 @@ -13,22 +13,25 @@ This section describes how to migrate the `commands` section to devfile v2.x. A . Id and label for composite commands. . Run exec commands as specific user. . Devfile metadata: add a link to an external website. -. Stack and devfile matching rules. +. Stack or devfile matching rules. [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]. +For a deeper understanding of migrating commands, go to the following GitHub issues: -* Environment variables for a specific command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue]. +* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug] -* Renaming workdir into workingDir. See https://github.com/che-incubator/devworkspace-api/issues/22[corresponding issue]. +* link:https://github.com/devfile/api/issues/56[Apply command] -* Id and label for composite commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue]. +* link:https://github.com/devfile/api/issues/21[Environment variables for a specific command] -* Run exec commands as specific user. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue]. +* link:https://github.com/devfile/api/issues/22[Renaming workdir into workingDir] -* 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/devfile/api/issues/18[Id and label for composite commands] -* Stack and devfile matching rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue]. +* link:https://github.com/devfile/api/issues/34[Run exec commands as specific user] + +* link:https://github.com/devfile/api/issues/38[Devfile metadata: add a link to an external website] + +* 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 fc886947..7837da66 100644 --- a/docs/modules/user-guide/partials/proc_migrating-components.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc @@ -2,13 +2,21 @@ = 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. +<<<<<<< HEAD +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. +======= +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. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 .Procedure . 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`. +<<<<<<< HEAD +To get a better syntax validation, define a component as a polymorphic type and implement it 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`. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 + [source,yaml] ---- @@ -26,32 +34,21 @@ components: uri: https://.../mongo.yaml ---- + -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]. - [role="_additional-resources"] .Additional resources - -* 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]. +<<<<<<< HEAD +For a deeper understanding of migrating components, go to the following GitHub issues: +======= +Go to the following GitHub issues: +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 + +* 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 containers] +* link:https://github.com/devfile/api/issues/9[Replace alias with name] +* 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 53bdc0f3..172d5cd1 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,20 +2,82 @@ = Migrating plug-ins [role="_abstract"] -This section describes how to migrate plug-ins to devfile v2.x. Plug-ins are now specified using a devfile. A plug-in specified in a v1.0 `meta.yaml` does not work as it is 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. + Additionally, v2.x devfiles include the following new features: -* Parents allow users to reuse an existing devfile and partially replace plug-in functionality. -* Eclipse Che IDEs and their tooling can be specified as attributes in a v2.x devfile or in a distinct YAML file, for example: `.che/che-editor.yaml` or `.che/che-theia-plugin.yaml`. +. Specify a plug-in using a devfile. ++ +[source,yaml] +---- +v2.0 +--- +java8.yaml +--- +schemaVersion: 2.0.0 +metadata: + publisher: redhat + name: java8 + version: 0.57.0 + displayName: Language Support for Java 8 + title: Language Support for Java(TM) by ... + description: Java Linting, Intellisense ... + icon: https://.../logo-eclipseche.svg + repository: https://github.../vscode-java + category: Language + firstPublicationDate: "2020-02-20" + plug-inType: che-theia-vsx # <== mandatory + # for plug-ins + # Valid types: + # che-theia-vsx + # che-editor, + # che-theia-plug-in, + # che-theia-ext, + # generic-service, + # generic-ui +parent: + id: redhat/theia-vsx-template/latest + components: + - container: + name: vsx-installer + env: + - name: VSX_LIST + value: java-dbg.vsix,java.vsix +components: + - kubernetes: + name: ... + reference: ... + - container: + image: ...che-sidecar-java + name: vscode-java + memoryLimit: "1500Mi" + volumeMounts: + - path: "/home/theia/.m2" + name: m2 + - volume: + name: m2 +---- ++ +. Reference a plug-in from a distinct devfile. ++ +[source,yaml] +---- +v2.0 +--- +devfile.yaml +--- +components: +- plug-in: + name: java language server + id: redhat/java11/0.57.0 # other then by `id`, a plug-in + # can be referenced by `uri` and + # `kubernetes` +---- ++ [role="_additional-resources"] .Additional resources -To learn more about plug-ins in v2.x devfiles, go to the GitHub issues on the following topics: - -* link:https://github.com/eclipse/che/issues/18669[Devfile plugins not suited to specify Che-Theia plugins]. -* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plugins support in devfile v2.x]. -* link:https://github.com/devfile/api/issues/364[Plugins' replacement]. -* link:https://github.com/devfile/api/issues/31[Better plugin 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 e6616ef6..8552c812 100644 --- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc @@ -2,13 +2,18 @@ = 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 devfiles v2.x. A project specified in a devfile v1.x still works in a devfile v2.x. .Procedure -* 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). -+ +<<<<<<< HEAD + 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. +======= + 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. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 + .starterProjects and projects description + ==== [source,yaml] ---- @@ -18,10 +23,15 @@ 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]. + +<<<<<<< HEAD +For a deeper understanding of migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. +======= +Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects]. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 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..e43f94cc 100644 --- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc @@ -2,12 +2,12 @@ = Migrating schema version [role="_abstract"] -This section describes how to migrate schema version. +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 -* Replace `apiVersion: 1.0.0` by `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"] |==== | @@ -29,9 +29,13 @@ metadata: name: devfile-sample ---- |==== - - ++ [role="_additional-resources"] .Additional resources -* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue] + +<<<<<<< HEAD +For a deeper understanding of migrating schema versions, go to the following GitHub issue: 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]. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 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..3378cbcb 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,21 +2,30 @@ = 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). +<<<<<<< HEAD +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. +======= +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. +>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4 .Prerequisites -* xref:adding-schema-version-to-a-devfile.adoc[] -* xref:adding-a-name-to-a-devfile.adoc[] +* 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[]. +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 -* A parent devfile can be referenced in 3 different ways: `registry`, `uri` or `kubernetes`. -+ +You can refer to a parent devfile in three different ways: + +* 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] ---- @@ -28,10 +37,10 @@ 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). +Use the URI if it has been published on a static http server like gist or pastebin. [source,yaml] ---- @@ -39,13 +48,18 @@ 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 ---- ==== -+ + .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] ---- @@ -62,5 +76,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[]