diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc index 6339fc16..6485d215 100644 --- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc @@ -2,33 +2,33 @@ = 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. +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. .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. +. 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/Devfile Matching Rules. +. Stack and 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]. +* 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]. -* Environment Varibables for a Specific Command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue]. +* Environment variables for a specific command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue]. * Renaming workdir into workingDir. See https://github.com/che-incubator/devworkspace-api/issues/22[corresponding issue]. -* Id and label for Composite Commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue]. +* Id and label for composite commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue]. -* Run exec Commands as Specific User. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue]. +* Run exec commands as specific user. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue]. * Devfile metadata: add a link to an external website. See https://github.com/che-incubator/devworkspace-api/issues/38[corresponding issue]. -* Stack/Devfile Matching Rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue]. \ No newline at end of file +* Stack and devfile matching rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue]. 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..53bdc0f3 100644 --- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc +++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc @@ -2,79 +2,20 @@ = Migrating plug-ins [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 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. -.Procedure +Additionally, v2.x devfiles include the following new features: -. 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. - -[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" - pluginType: che-theia-vsx # <== mandatory - # for plugins - # Valid types: - # che-theia-vsx - # che-editor, - # che-theia-plugin, - # 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 ----- - -. And then can be referenced from a distinct devfile: - -[source,yaml] ----- -v2.0 ---- -devfile.yaml ---- -components: -- plugin: - name: java language server - id: redhat/java11/0.57.0 # other then by `id`, a plugin - # can be referenced by `uri` and - # `kubernetes` ----- +* 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`. [role="_additional-resources"] .Additional resources -* See https://github.com/che-incubator/devworkspace-api/issues/31[corresponding issue]. + +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].