Authoring devfile version 1 and 2 (#2012)

* devfile

* Update modules/end-user-guide/pages/authoring-devfiles-version-2.adoc

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* Update modules/end-user-guide/pages/authoring-devfiles-version-1.adoc

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* Update modules/end-user-guide/pages/authoring-devfiles-version-1.adoc

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

* nav

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

.vale/styles/IBM/Terms.yml

@@ -139,7 +139,6 @@ swap:
   notion: concept
   off-premise: on-premises|off-premises|onsite|offsite
   offline storage: auxiliary storage
-  okay: OK
   on ramp: access method
   on the fly: dynamically|as needed|in real time|immediately
   on the other hand: however|alternatively|conversely

.vale/styles/Vocab/Che/reject.txt

@@ -10,7 +10,6 @@ look up
 maybe
 mostly
 now
-operator
 our
 out of the box
 probably

modules/administration-guide/partials/assembly_calculating-che-resource-requirements.adoc

@@ -24,8 +24,7 @@ ifeval::["{project-context}" == "che"]
 endif::[]
 * xref:installation-guide:configuring-the-che-installation.adoc[]
 * xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc[]
-* xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[]
-* xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc#a-minimal-devfile_{context}[A minimal devfile]
+* xref:end-user-guide:authoring-devfiles-version-2.adoc[]
 * xref:authenticating-users.adoc[]
 * link:https://github.com/eclipse-che/che-plugin-registry[{prod-short} plug-ins registry repository]
 

modules/administration-guide/partials/proc_building-a-custom-devfile-registry-image.adoc

@@ -12,7 +12,7 @@ The image contains all sample projects referenced in devfiles.
 
 * A running installation of link:http://podman.io[podman] or link:http://docker.io[docker].
 
-* Valid content for the devfile to add. See: xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[].
+* Valid content for the devfile to add. See: xref:end-user-guide:authoring-devfiles-version-2.adoc[].
 
 .Procedure
 
@@ -33,7 +33,7 @@ include::example$snip_{project-context}-clone-the-devfile-registry-repository.ad
 ----
 ====
 
-. Add valid content in the `devfile.yaml` file. For a detailed description of the devfile format, see xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[].
+. Add valid content in the `devfile.yaml` file. For a detailed description of the devfile format, see xref:end-user-guide:authoring-devfiles-version-2.adoc[].
 
 . Ensure that the `meta.yaml` file conforms to the following structure:
 +
@@ -64,6 +64,6 @@ To display full options for the `build.sh` script, use the `--help` parameter.
 
 .Additional resources
 
-* xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[].
+* xref:end-user-guide:authoring-devfiles-version-2.adoc[].
 
 * xref:running-custom-registries.adoc[].

modules/administration-guide/partials/proc_workspaces-requirements.adoc

@@ -12,7 +12,7 @@ These examples demonstrate the necessity of a proper calculation:
 
 .Procedure
 
-. Identify the workspace components explicitly specified in the `components` section of the xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[].
+. Identify the workspace components explicitly specified in the `components` section of the xref:end-user-guide:authoring-devfiles-version-2.adoc[].
 
 . Identify the implicit workspace components:
 +

modules/end-user-guide/examples/che-adding-a-git-project-into-a-workspace-using-a-devfile.adoc

@@ -18,4 +18,4 @@ projects:
       location: 'https://github.com/__<github-organization>__/__<{project-context}>__.git'
 ----
 +
-For additional information, see the xref:configuring-a-workspace-using-a-devfile.adoc#devfile-reference_{context}[Devfile reference] section.
+For additional information, see the xref:authoring-devfiles-version-1.adoc[Devfile reference] section.

modules/end-user-guide/nav.adoc

@@ -4,7 +4,6 @@
 ** xref:navigating-che-using-the-dashboard.adoc[]
 ** xref:importing-certificates-to-browsers.adoc[]
 ** xref:accessing-che-from-openshift-developer-perspective.adoc[]
-
 * xref:che-theia-ide-basics.adoc[]
 ** xref:defining-custom-commands-for-che-theia.adoc[]
 ** xref:version-control.adoc[]
@@ -22,6 +21,9 @@
 ** xref:remotely-accessing-workspaces.adoc[]
 ** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc[]
 ** xref:authenticating-on-scm-server-with-a-personal-access-token.adoc[]
+* xref:authoring-devfiles.adoc[]
+** xref:authoring-devfiles-version-1.adoc[]
+** xref:authoring-devfiles-version-2.adoc[]
 * xref:customizing-developer-environments.adoc[]
 ** xref:what-is-a-che-theia-plug-in.adoc[]
 ** xref:adding-a-vs-code-extension-to-a-workspace.adoc[]

modules/end-user-guide/pages/authoring-devfiles-version-1.adoc

@@ -0,0 +1,7 @@
+[id="authoring-devfiles-version-1"]
+// 
+:navtitle: Authoring devfiles version 1
+:keywords: end-user-guide, authoring-devfiles-version-1
+:page-aliases: .:authoring-devfiles-version-1
+
+include::partial$assembly_authoring-devfiles-version-1.adoc[]

modules/end-user-guide/pages/authoring-devfiles-version-2.adoc

@@ -0,0 +1,7 @@
+[id="authoring-devfiles-version-2"]
+// 
+:navtitle: Authoring devfiles version 2
+:keywords: end-user-guide, authoring-devfiles-version-2
+:page-aliases: .:authoring-devfiles-version-2
+
+include::partial$assembly_authoring-devfiles-version-2.adoc[]

modules/end-user-guide/pages/authoring-devfiles.adoc

@@ -0,0 +1,7 @@
+[id="authoring-devfiles"]
+// 
+:navtitle: Authoring devfiles
+:keywords: end-user-guide, authoring-devfiles
+:page-aliases: .:authoring-devfiles, configuring-a-workspace-using-a-devfile, making-a-workspace-portable-using-a-devfile
+
+include::partial$assembly_authoring-devfiles.adoc[]

modules/end-user-guide/partials/assembly_authoring-devfiles-version-1.adoc

@@ -0,0 +1,22 @@
+:parent-context-of-authoring-devfiles-version-1: {context}
+
+[id="authoring-devfiles-version-1_{context}"]
+= Authoring devfiles version 1
+
+:context: authoring-devfiles-version-1
+
+This section explains the concept of a devfile and how to configure a {prod-short} workspace by using a devfile of the 1.0 specification. 
+
+include::partial$con_what-is-a-devfile.adoc[leveloffset=+1]
+
+include::partial$con_a-minimal-devfile.adoc[leveloffset=+1]
+
+include::partial$proc_generating-workspace-names.adoc[leveloffset=+1]
+
+include::partial$proc_writing-a-devfile-for-your-project.adoc[leveloffset=+1]
+
+include::partial$ref_devfile-reference.adoc[leveloffset=+1]
+
+include::partial$ref_objects-supported-in-che.adoc[leveloffset=+1]
+
+:context: {parent-context-of-authoring-devfiles-version-1}

modules/end-user-guide/partials/assembly_authoring-devfiles-version-2.adoc

@@ -0,0 +1,21 @@
+:parent-context-of-authoring-devfiles-version-2: {context}
+
+[id="authoring-devfiles-version-2_{context}"]
+= Authoring devfiles version 2
+
+:context: authoring-devfiles-version-2
+
+This section explains the concept of the devfile 2.0 specification and how to configure a {prod-short} workspace by using a devfile 2.0. 
+
+.Prerequisites:
+* An instance of {prod-short} with the DevWorkspace Operator enabled, see xref:installation-guide:enabling-dev-workspace-engine.adoc[]
+
+.Procedure
+//TODO - Figure out whether we want to duplicate, single source or just reference devfile docs here
+* To create devfiles with the 2.0 specification, see link:https://docs.devfile.io/devfile/2.0.0/user-guide/authoring-stacks.html[]
+
+.Additional resources
+
+* link:https://redhat-developer.github.io/devfile/devfile[Devfile 2.0 specification]
+
+:context: {parent-context-of-configuring-a-workspace-using-a-devfile}

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

@@ -0,0 +1,12 @@
+:parent-context-of-authoring-devfiles: {context}
+
+[id="authoring-devfiles_{context}"]
+= Authoring devfiles
+
+:context: authoring-devfiles
+
+* xref:authoring-devfiles-version-1.adoc[]
+
+* xref:authoring-devfiles-version-2.adoc[]
+
+:context: {parent-context-of-authoring-devfiles}

modules/end-user-guide/partials/assembly_configuring-a-workspace-with-dashboard.adoc

@@ -16,6 +16,6 @@ include::partial$proc_configuring-the-workspace-and-adding-tooling.adoc[leveloff
 
 .Additional resources
 
-* xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc[]
+* xref:end-user-guide:authoring-devfiles-version-2.adoc[]
 
 :context: {parent-context-of-configuring-a-workspace-with-dashboard}

modules/end-user-guide/partials/assembly_creating-a-workspace-from-code-sample.adoc

@@ -12,7 +12,7 @@ This section explains how to create a workspace from code sample or devfile temp
 . Creating a workspace from sample using the xref:creating-a-workspace-from-get-started-view-of-user-dashboard_{context}[Get Started view].
 . Creating a custom workspace using templates on xref:creating-a-custom-workspace-from-a-template_{context}[Custom Workspace view].
 
-For more information about devfiles, see xref:configuring-a-workspace-using-a-devfile.adoc[].
+For more information about devfiles, see xref:authoring-devfiles-version-2.adoc[].
 
 include::partial$proc_creating-a-workspace-from-user-dashboard-get-started.adoc[leveloffset=+1]
 

modules/end-user-guide/partials/assembly_creating-a-workspace-from-remote-devfile.adoc

@@ -21,6 +21,6 @@ include::partial$proc_allowing-users-to-define-workspace-deployment-labels-and-a
 
 .Additional resources
 
-* xref:configuring-a-workspace-using-a-devfile.adoc[]
+* xref:authoring-devfiles-version-2.adoc[]
 
 :context: {parent-context-of-creating-a-workspace-from-remote-devfile}

modules/end-user-guide/partials/assembly_defining-custom-commands-for-che-theia.adoc

@@ -17,7 +17,7 @@ This is useful, for example, for:
 * Allowing lead developers to customize workspaces based on team requirements.
 * Reducing time needed to onboard new team members.
 
-See also xref:configuring-a-workspace-using-a-devfile.adoc[].
+See also xref:authoring-devfiles-version-2.adoc[].
 
 include::partial$con_che-theia-task-types.adoc[leveloffset=+1]
 

modules/end-user-guide/partials/con_additional-tools-in-the-che-workspace.adoc

@@ -23,4 +23,4 @@ The devfile can also further the plug-in configuration, such as defining memory
 
 .Additional resources
 
-* xref:configuring-a-workspace-using-a-devfile.adoc#adding-components-to-a-devfile_{context}[Adding components to a devfile]
+* xref:authoring-devfiles-version-1.adoc[Adding components to a devfile]

modules/end-user-guide/partials/proc_allowing-users-to-define-workspace-deployment-labels-and-annotations.adoc

@@ -11,7 +11,7 @@ This section describes how to customize workspace deployment labels and annotati
 .Prerequisites
 
 * A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[].
-* A publicly accessible standalone `devfile.yaml` file. See xref:configuring-a-workspace-using-a-devfile.adoc[] for detailed information about creating and using devfiles.
+* A publicly accessible standalone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles.
 
 .Procedure
 

modules/end-user-guide/partials/proc_changing-the-configuration-of-an-existing-workspace.adoc

@@ -29,4 +29,4 @@ This section describes how to change the configuration of an existing workspace
 
 ** Review *{orch-namespace}*.
 
-. From the *Devfile* tab, edit YAML configuration of the workspace. See xref:configuring-a-workspace-using-a-devfile.adoc[].
+. From the *Devfile* tab, edit YAML configuration of the workspace. See xref:authoring-devfiles-version-2.adoc[].

modules/end-user-guide/partials/proc_che-including-kubernetes-applications-in-a-workspace-devfile-definition.adoc

@@ -7,7 +7,7 @@
 
 This procedure describes how to define a {prod-short} workspace devfile to include a {orch-name} application.
 
-The devfile format is used to define a {prod-short} workspace, and its format is described in the xref:configuring-a-workspace-using-a-devfile.adoc[] section.
+The devfile format is used to define a {prod-short} workspace, and its format is described in the xref:authoring-devfiles-version-2.adoc[] section.
 
 .Prerequisites
 

modules/end-user-guide/partials/proc_creating-a-workspace-by-importing-the-source-code-of-a-project.adoc

@@ -18,7 +18,7 @@ This section describes how to create a new workspace for editing an existing cod
 A user can progress with two methods that have to be applied *before* starting a workspace:
 
 * xref:creating-a-custom-workspace-from-the-dashboard_{context}[Select a sample from the Dashboard, then change the devfile to include your project]
-* xref:configuring-a-workspace-using-a-devfile.adoc[]
+* xref:authoring-devfiles-version-2.adoc[]
 
 To create a new workspace for editing an existing codebase, use one of the following methods *after* the workspace has been started:
 
@@ -54,7 +54,7 @@ projects:
       type: git
       location: 'https://github.com/eclipse-che/che-server.git'
 ----
-See the xref:configuring-a-workspace-using-a-devfile.adoc#devfile-reference_{context}[Devfile reference].
+See the xref:authoring-devfiles-version-1.adoc[Devfile reference].
 ====
 
 * To open the workspace, click the btn:[Create & Open] button.
@@ -81,7 +81,7 @@ projects:
       type: git
       location: 'https://github.com/eclipse-che/che-server.git'
 ----
-See the xref:configuring-a-workspace-using-a-devfile.adoc#devfile-reference_{context}[Devfile reference].
+See the xref:authoring-devfiles-version-1.adoc[Devfile reference].
 ====
 
 [id="editing-the-commands-after-importing-a-project_{context}"]

modules/end-user-guide/partials/proc_creating-a-workspace-from-a-feature-branch-of-a-git-repository.adoc

@@ -9,7 +9,7 @@ A {prod-short} workspace can be created by pointing to devfile that is stored in
 
 .Prerequisites
 * A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[].
-* The `devfile.yaml` or `.devfile.yaml` file is located in the root folder of a Git repository, on a specific branch of the user's choice that is accessible over HTTPS. See xref:configuring-a-workspace-using-a-devfile.adoc[] for detailed information about creating and using devfiles.
+* The `devfile.yaml` or `.devfile.yaml` file is located in the root folder of a Git repository, on a specific branch of the user's choice that is accessible over HTTPS. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles.
 
 .Procedure
 Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#__<GitHubBranch>__]`

modules/end-user-guide/partials/proc_creating-a-workspace-from-the-default-branch-of-a-git-repository.adoc

@@ -15,7 +15,7 @@ The factory URL exist in two forms:
 .Prerequisites
 
 * A running instance of {prod}. See xref:installation-guide:installing-che.adoc[].
-* The Git repository __<GIT_REPOSITORY_URL>__ is available over HTTPS and contains a `devfile.yaml` or `.devfile.yaml` in the root folder. See xref:configuring-a-workspace-using-a-devfile.adoc[].
+* The Git repository __<GIT_REPOSITORY_URL>__ is available over HTTPS and contains a `devfile.yaml` or `.devfile.yaml` in the root folder. See xref:authoring-devfiles-version-2.adoc[].
 
 
 .Procedure

modules/end-user-guide/partials/proc_creating-a-workspace-from-with-a-publicly-accessible-standalone-devfile-using-http.adoc

@@ -9,7 +9,7 @@ A workspace can be created using a devfile, the URL of which is pointing to the
 
 .Prerequisites
 * A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[].
-* The publicly-accessible standalone `devfile.yaml` file. See xref:configuring-a-workspace-using-a-devfile.adoc[] for detailed information about creating and using devfiles.
+* The publicly-accessible standalone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles.
 
 .Procedure
 . Execute the workspace by opening the following URL: `pass:c,a,q[{prod-url}/#https://__<yourhosturl>__/devfile.yaml]`

modules/end-user-guide/partials/proc_creating-a-workspace-using-chectl-and-a-local-devfile.adoc

@@ -10,7 +10,7 @@ A {prod-short} workspace can be created by pointing the `{prod-cli}` tool to a l
 .Prerequisites
 * A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[].
 * The {prod-short} CLI management tool. See xref:overview:using-the-chectl-management-tool.adoc[].
-* The devfile is available on the local filesystem in the current working directory. See xref:configuring-a-workspace-using-a-devfile.adoc[] for detailed information about creating and using devfiles.
+* The devfile is available on the local filesystem in the current working directory. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles.
 * You are logged in to {prod}. See xref:end-user-guide:navigating-{prod-id-short}-using-the-dashboard.adoc#logging-in-to-{prod-id-short}-using-{prod-cli}_{context}[How to login into {prod-short} using {prod-cli}]
 
 

modules/end-user-guide/partials/proc_overriding-devfile-values-using-factory-parameters.adoc

@@ -15,7 +15,7 @@ Values in the following sections of a remote devfile can be overridden using spe
 .Prerequisites
 
 * A running instance of {prod}. To install an instance of {prod}, see xref:installation-guide:installing-che.adoc[].
-* A publicly accessible standalone `devfile.yaml` file. See xref:configuring-a-workspace-using-a-devfile.adoc[] for detailed information about creating and using devfiles.
+* A publicly accessible standalone `devfile.yaml` file. See xref:authoring-devfiles-version-2.adoc[] for detailed information about creating and using devfiles.
 
 .Procedure
 

modules/end-user-guide/partials/proc_using-private-container-registries.adoc

@@ -35,7 +35,7 @@ This section describes the necessary steps to use container images from private
 
 . See that there is a new entry in the btn:[Container Registries] tab.
 
-. Create a workspace that uses a container image from the specified container registry. See xref:configuring-a-workspace-using-a-devfile.adoc[].
+. Create a workspace that uses a container image from the specified container registry. See xref:authoring-devfiles-version-2.adoc[].
 
 .Additional resources
 

modules/end-user-guide/partials/ref_che-theia-plug-in-metadata.adoc

@@ -50,7 +50,7 @@ endif::[]
 
 .`spec` attributes
 |===
-|`endpoints` | Optional; plugin endpoint. See xref:configuring-a-workspace-using-a-devfile.adoc#endpoints_{context}[]
+|`endpoints` | Optional; plugin endpoint.
 |`containers`| Optional; sidecar containers for the plug-in. Che Plugin and VS Code extension supports only one container
 |`initContainers`| Optional; sidecar init containers for the plug-in
 |`workspaceEnv`| Optional; environment variables for the workspace

modules/extensions/partials/assembly_telemetry-overview.adoc

@@ -17,7 +17,7 @@ This documentation includes a guide describing how to make your own telemetry cl
 * Duration of a workspace utilization
 * User-driven actions such as file editing, committing, and pushing to remote repositories.
 * The list of plug-ins enabled in a workspace
-* Programming languages and devfiles used in workspaces. See xref:end-user-guide:configuring-a-workspace-using-a-devfile.adoc#what-is-a-devfile_{context}[]
+* Programming languages and devfiles used in workspaces. See xref:end-user-guide:authoring-devfiles-version-2.adoc[]
 
 == How it works
 [id="how-it-works_{context}"]
@@ -29,4 +29,4 @@ If the {prod-short} workspace has a telemetry back-end container running, and it
 image::telemetry/telemetry_diagram.png[]
 
 
-:context: {parent-context-of-telemetry-overview}
+:context: {parent-context-of-telemetry-overview}