Style Guide Review

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

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

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]

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]

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

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=<repository URL> | 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

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