Update Authoring Documents

.gitignore

@@ -15,6 +15,7 @@
 .DS_Store
 .vale.ini
 .yarnrc
+.idea/
 /build/
 /out/
 /node_modules/

docs/modules/user-guide/attachments/api-reference/next/index.html

@@ -1327,7 +1327,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
 
                                                                                                                                                                                 </dt>
                                                                                                                                                                                 <dd>
-                                                                                                                                                                                    <p>Path of source directory to establish build context. Defaults to ${PROJECT_ROOT} in the container</p>
+                                                                                                                                                                                    <p>Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container</p>
 
                                                                                                                                                                                     <div class="json-inner-schema">
 
@@ -3734,7 +3734,7 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
 
                                                                                                                                                                                                                 </dt>
                                                                                                                                                                                                                 <dd>
-                                                                                                                                                                                                                    <p>Path of source directory to establish build context. Defaults to ${PROJECT_ROOT} in the container</p>
+                                                                                                                                                                                                                    <p>Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container</p>
 
                                                                                                                                                                                                                     <div class="json-inner-schema">
 
@@ -4787,6 +4787,21 @@ <h3 class="panel-title">Devfile schema - Version 2.2.0-alpha</h3>
                                                                             <div class="json-inner-schema">
 
 
+                                                                            </div>
+                                                                        </dd>
+                                                                        <dt data-property-name="version">
+                                                                            <span class="json-property-name">version:</span>
+
+                                                                            <span class="json-property-type">string</span>
+                                                                            <span class="json-property-range" title="Value limits"></span>
+
+                                                                                <span class="json-property-pattern" title="String pattern">, must match <span class="json-schema--regex">^(latest)|(([1-9])\.([0-9]+)\.([0-9]+)(\-[0-9a-z-]+(\.[0-9a-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?)$</span></span>
+                                                                        </dt>
+                                                                        <dd>
+                                                                            <p>Specific stack/sample version to pull the parent devfile from, when using id in the parent reference. To specify <code>version</code>, <code>id</code> must be defined and used as the import reference source. <code>version</code> can be either a specific stack version, or <code>latest</code>. If no <code>version</code> specified, default version will be used.</p>
+
+                                                                            <div class="json-inner-schema">
+
                                                                             </div>
                                                                         </dd>
                                                             </dl>

docs/modules/user-guide/nav.adoc

@@ -10,10 +10,12 @@
 **** xref:adding-a-command-section-to-a-devfile.adoc[]
 **** xref:adding-a-command-group-to-a-devfile.adoc[]
 **** xref:adding-exec-commands-to-a-devfile.adoc[]
+**** xref:adding-apply-commands-to-a-devfile.adoc[]
 **** xref:adding-composite-commands-to-a-devfile.adoc[]
 *** xref:adding-components-to-a-devfile.adoc[]
 **** xref:adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc[]
 **** xref:adding-a-container-component-to-a-devfile.adoc[]
+**** xref:adding-a-image-component-to-a-devfile.adoc[]
 **** xref:adding-a-volume-component-to-a-devfile.adoc[]
 **** xref:specifying-persistent-storage.adoc[]
 **** xref:limiting-resources-usage.adoc[]

docs/modules/user-guide/pages/adding-a-image-component-to-a-devfile.adoc

@@ -0,0 +1,6 @@
+:description: Adding an image component to a devfile
+:navtitle: Adding an image component
+:keywords: authoring, stack, components
+:page-aliases:
+
+include::partial$proc_adding-a-image-component-to-a-devfile.adoc[]

docs/modules/user-guide/pages/adding-apply-commands-to-a-devfile.adoc

@@ -0,0 +1,6 @@
+:description: Adding apply commands to a devfile
+:navtitle: Adding apply commands to a devfile
+:keywords: command, devfile
+
+
+include::partial$proc_adding-apply-commands-to-a-devfile.adoc[]

docs/modules/user-guide/partials/assembly_adding-commands-to-a-devfile.adoc

@@ -16,6 +16,7 @@ You can use a devfile to specify commands to run in a workspace. Every command c
 * xref:adding-a-command-section-to-a-devfile.adoc[]
 * xref:adding-a-command-group-to-a-devfile.adoc[]
 * xref:adding-exec-commands-to-a-devfile.adoc[]
+* xref:adding-apply-commands-to-a-devfile.adoc[]
 * xref:adding-composite-commands-to-a-devfile.adoc[]
 
 [role="_additional-resources"]

docs/modules/user-guide/partials/assembly_authoring-devfiles.adoc

@@ -14,14 +14,13 @@ endif::[]
 [role="_abstract"]
 A devfile is a `yaml` file. After you include it in your local environment, the devfile provides ways to automate your processes. Tools like `odo` run the devfile and apply its guidelines to your environment. You can configure the devfile based on your unique development needs. See the following documents to help you author a devfile based on your development needs:
 
-* xref:adding-schema-version-to-a-devfile.adoc[]
-* xref:adding-a-name-to-a-devfile.adoc[]
 * xref:adding-schema-version-to-a-devfile.adoc[]
 * xref:adding-a-name-to-a-devfile.adoc[]
 * xref:adding-projects-to-a-devfile.adoc[]
 * xref:adding-commands-to-a-devfile.adoc[]
 * xref:adding-components-to-a-devfile.adoc[]
 * xref:adding-attributes-to-a-devfile.adoc[]
+* xref:adding-event-bindings.adoc[]
 * xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
 
 // [role="_additional-resources"]

docs/modules/user-guide/partials/proc_adding-a-command-group-to-a-devfile.adoc

@@ -19,12 +19,13 @@ Create command groups to help automate your devfile.
 * `run`
 * `test`
 * `debug`
+* `deploy`
 +
 . At most, there can only be one default command for each group kind. Set the default command by specifying a `true` value for `isDefault`.
 +
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
   name: mydevfile
 projects:
@@ -54,3 +55,46 @@ commands:
         kind: build
         isDefault: true
 ----
++
+. Use the `deploy` kind to reference a deploy command for an outerloop scenario.
++
+[source,yaml]
+----
+schemaVersion: 2.2.0
+metadata:
+  name: python
+  version: 1.0.0
+  provider: Red Hat
+  supportUrl: https://github.com/devfile-samples/devfile-support#support-information
+  attributes:
+    alpha.dockerimage-port: 8081
+parent:
+  id: python
+  registryUrl: "https://registry.devfile.io"
+components:
+  - name: outerloop-build
+    image:
+      imageName: python-image:latest
+      dockerfile:
+        uri: docker/Dockerfile
+        buildContext: .
+        rootRequired: false
+  - name: outerloop-deploy
+    kubernetes:
+      uri: outerloop-deploy.yaml
+commands:
+  - id: build-image
+    apply:
+      component: outerloop-build
+  - id: deployk8s
+    apply:
+      component: outerloop-deploy
+  - id: deploy
+    composite:
+      commands:
+        - build-image
+        - deployk8s
+      group:
+        kind: deploy
+        isDefault: true
+----

docs/modules/user-guide/partials/proc_adding-a-container-component-to-a-devfile.adoc

@@ -46,7 +46,7 @@ A devfile can contain one or more components of the `container` type. The `compo
 .A minimal `container` component
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
     name: mydevfile
 components:
@@ -67,7 +67,7 @@ For the `container` component to have access to the project sources, you must se
 +
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
     name: mydevfile
 components:
@@ -81,6 +81,26 @@ components:
 +
 The sources are mounted on a location stored in the `PROJECTS_ROOT` environment variable that is made available in the running container of the image. This location defaults to `/projects`. If `sourceMapping` is defined in the container, it overrides the `PROJECT_ROOT` value and mounts the source to the path defined by `sourceMapping`.
 
+. Specify a volume
++
+For the `container` component to have a shared volume. You must define a volume component in the devfile, and reference the volume using `volumeMount` in container component. For more information on volume component, see xref:adding-a-volume-component-to-a-devfile.adoc[]
++
+[source,yaml]
+----
+components:
+  - name: mycontainer
+    container:
+      image: java11-maven:next
+      memoryLimit: 768Mi
+      mountSources: true
+      volumeMounts:
+        - name: m2
+          path: /home/user/.m2
+  - name: m2
+    volume:
+      size: 1Gi
+----
+
 . Container Entrypoint
 +
 Use the `command` attribute of the `container` type to modify the `entrypoint` command of the container created from the image. The availability of the `sleep` command and the support for the `infinity` argument depend on the base image used in the particular images.

docs/modules/user-guide/partials/proc_adding-a-image-component-to-a-devfile.adoc

@@ -0,0 +1,71 @@
+[id="proc_adding-a-image-component-to-a-devfile_{context}"]
+= Adding an image component to a devfile
+
+[role="_abstract"]
+You can add an `image` component to a devfile.
+
+.Prerequisites
+
+* xref:adding-schema-version-to-a-devfile.adoc[]
+* xref:adding-a-name-to-a-devfile.adoc[]
+* xref:adding-components-to-a-devfile.adoc[]
+
+.Procedure
+
+. Define a component using the type `image`.
++
+Specify the location of the Dockerfile using the `uri` property. Specify arguments to be passed during the build with `args`. `buildContext` is the path of source directory to establish build context. If `rootRequired` is set to true, a privileged builder pod is required. The built container will be stored in the image provided by `imageName`.
++
+.An `image` dockerfile component
+[source,yaml]
+----
+components:
+  - name: outerloop-build
+    image:
+      imageName: python-image:latest
+      autoBuild: true
+      dockerfile:
+        uri: docker/Dockerfile
+        args:
+            - "MY_ENV=/home/path"
+        buildContext: .
+        rootRequired: false
+----
++
+Alternatively, specify `git` and `devfileRegistry` as the image source.
++
+When specifying `git`, `fileLocation` refers to the location of the Dockerfile in the git repository. Specify the `remotes` for the git repository and a `checkoutFrom` to indicate which `revision` to check the source from.
++
+.An `image` dockerfile component with git source
+[source,yaml]
+----
+components:
+  - name: outerloop-build
+    image:
+      imageName: python-image:latest
+      dockerfile:
+        git:
+          fileLocation: "uri/Dockerfile"
+          checkoutFrom:
+            revision: "main"
+            remote: "origin"
+          remotes:
+            "origin": "https://github.com/myorg/myrepo"
+        buildContext: .
+----
++
+When specifying `devfileRegistry`, `id` refers to the Id in a devfile registry that contains a Dockerfile. `registryUrl` refers to the Devfile Registry URL to pull the Dockerfile from
++
+.An `image` dockerfile component with devfileRegistry source
+[source,yaml]
+----
+components:
+  - name: outerloop-build
+    image:
+      imageName: python-image:latest
+      dockerfile:
+        devfileRegistry:
+          id: python
+          registryUrl: myregistry.devfile.com
+        buildContext: .
+----

docs/modules/user-guide/partials/proc_adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc

@@ -52,5 +52,7 @@ You can add either a `kubernetes` or `openshift` component to a devfile.
 +
 . Specify the endpoint through the endpoint property with `kubernetes` or `openshift` components.
 
-. Associate `kubernetes` or `openshift` components with `Apply` commands. If you do not associate `Apply` commands, they are assumed to be applied at start up.
+. By default `kubernetes` or `openshift` components are not going to be deployed. Specify `deployByDefault=true` if you want to apply the component at start up.
+
+. Associate `kubernetes` or `openshift` components with `Apply` commands wth `deploy` command group kind. If the `kubernetes` or `openshift` component uses an image built by an image component defined in the devfile, you can create a composite `deploy` command to build the image and deploy the Kubernetes or openshift component. For more information on `deploy` commands, see xref:adding-a-command-group-to-a-devfile.adoc[]
 +

docs/modules/user-guide/partials/proc_adding-a-name-to-a-devfile.adoc

@@ -31,7 +31,7 @@ Adding a name to a devfile is mandatory. Use the `name` attribute to define the
 
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
   name: devfile-sample
   version: 2.0.0

docs/modules/user-guide/partials/proc_adding-a-volume-component-to-a-devfile.adoc

@@ -18,7 +18,7 @@ You can use a `volume` component to share files among container components and c
 
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
     name: mydevfile
 components:
@@ -33,7 +33,7 @@ components:
 
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
     name: mydevfile
 components:

docs/modules/user-guide/partials/proc_adding-apply-commands-to-a-devfile.adoc

@@ -0,0 +1,48 @@
+[id="proc_adding-apply-commands-to-a-devfile_{context}"]
+= Adding apply commands to a devfile
+[role="_abstract"]
+
+Use the the `apply` command to apply a given component definition, usually a `kubernetes`, `openshift` or an `image` component. Apply commands are also typically bound to `preStart` and `postStop` events.
+
+. Define the `apply` command to apply a given component. In the following example, two apply commands reference an `image` component and a `kubernetes` component to build a docker image and to apply the deployment YAML for an outerloop scenario.
++
+[source,yaml]
+----
+schemaVersion: 2.2.0
+metadata:
+  name: python
+  version: 1.0.0
+  provider: Red Hat
+  supportUrl: https://github.com/devfile-samples/devfile-support#support-information
+  attributes:
+    alpha.dockerimage-port: 8081
+parent:
+  id: python
+  registryUrl: "https://registry.devfile.io"
+components:
+  - name: outerloop-build
+    image:
+      imageName: python-image:latest
+      dockerfile:
+        uri: docker/Dockerfile
+        buildContext: .
+        rootRequired: false
+  - name: outerloop-deploy
+    kubernetes:
+      uri: outerloop-deploy.yaml
+commands:
+  - id: build-image
+    apply:
+      component: outerloop-build
+  - id: deployk8s
+    apply:
+      component: outerloop-deploy
+  - id: deploy
+    composite:
+      commands:
+        - build-image
+        - deployk8s
+      group:
+        kind: deploy
+        isDefault: true
+----

docs/modules/user-guide/partials/proc_adding-attributes-to-a-devfile.adoc

@@ -27,7 +27,7 @@ When no editor is specified, a default editor is provided. To represent this use
 ====
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
   name: petclinic-dev-environment
   attributes:

docs/modules/user-guide/partials/proc_adding-components-to-a-devfile.adoc

@@ -140,6 +140,7 @@ Each component in a single devfile must have a unique name and use one of the ob
 . xref:adding-a-kubernetes-or-openshift-component-to-a-devfile.adoc[]
 . xref:adding-a-container-component-to-a-devfile.adoc[]
 . xref:adding-a-volume-component-to-a-devfile.adoc[]
+. xref:adding-a-image-component-to-a-devfile.adoc[]
 . xref:specifying-persistent-storage.adoc[]
 . xref:limiting-resources-usage.adoc[]
 . xref:defining-environment-variables.adoc[]

docs/modules/user-guide/partials/proc_adding-composite-commands-to-a-devfile.adoc

@@ -18,7 +18,7 @@ Connect multiple commands together by defining a composite command.
 +
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
   name: mydevfile
 projects:

docs/modules/user-guide/partials/proc_adding-exec-commands-to-a-devfile.adoc

@@ -11,7 +11,7 @@ Use the the `exec` command to automate the container actions.
 +
 [source,yaml]
 ----
-schemaVersion: 2.1.0
+schemaVersion: 2.2.0
 metadata:
   name: mydevfile
 projects: