Modified docs to adhere to schema_4th PR (#46)

* modified docs to adhere to schema_4th PR

minor tweaks to yaml

minor change to migrating commands doc

added infor on more devfile v2 features

removed procedure from plugin doc and other minor changes

fixed devfile v2.x

minor language change to bullet point

* fixec capitalization

* Update docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc

Co-authored-by: Robert Krátký <[email protected]>

* Update docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc

Co-authored-by: Robert Krátký <[email protected]>

* Update docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc

Co-authored-by: Robert Krátký <[email protected]>

* Update docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc

Co-authored-by: Robert Krátký <[email protected]>

* Update docs/modules/user-guide/partials/proc_migrating-commands.adoc

Co-authored-by: Robert Krátký <[email protected]>

Co-authored-by: jc-berger <>
Co-authored-by: Robert Krátký <[email protected]>

Author: jc-berger

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].
+* Stack and devfile matching rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue].

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].