Skip to content

Made docs adhere to style guide #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 19, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/modules/user-guide/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

** xref:adding-attributes-to-a-devfile.adoc[]
** xref:adding-event-bindings.adoc[]
** xref:refering-to-a-parent-devfile-in-a-devfile.adoc[]
** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]

* xref:migrating-to-devfile-v2.adoc[]
** xref:migrating-schema-version.adoc[]
Expand All @@ -25,7 +25,7 @@
** xref:migrating-plug-ins.adoc[]
** xref:migrating-commands.adoc[]
** xref:adding-event-bindings.adoc[]
** xref:refering-to-a-parent-devfile-in-a-devfile.adoc[]
** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]

* xref:api-reference.adoc[]
* xref:devfile-samples.adoc[]
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ endif::[]

:context: assembly_migrating-to-devfile-v2

This guide explains how to migrate an existing v1.0 devfile to v2.0.
The following documents explain how to migrate an existing v1.x devfile to a v2.x devfile:

* xref:migrating-schema-version.adoc[]
* xref:migrating-projects.adoc[]
Expand All @@ -24,10 +24,11 @@ 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].
For more information on migrating devfiles, go to the following GitHub issues:

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

Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,7 @@
= 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 a v2.x devfile. An event specified in a v1.x devfile still works in a v2.x devfile.

.Procedure

Expand Down Expand Up @@ -46,4 +42,5 @@ events:

[role="_additional-resources"]
.Additional resources
* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue].

For more information on adding event bindings, go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[lifecycle bindings to bind commands].
24 changes: 10 additions & 14 deletions docs/modules/user-guide/partials/proc_migrating-commands.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 the `commands` section to a v2.x devfile. A command specified in a v1.x devfile does not work in a v2.x devfile.

.Procedure

Expand All @@ -18,17 +18,13 @@ This section describes how to migrate the `commands` section to devfile v2.x. A
[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 more information on 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].

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

* 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 and devfile matching rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue].
* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug]
* link:https://github.com/devfile/api/issues/56[Apply command]
* link:https://github.com/devfile/api/issues/21[Environment variables for a specific command]
* link:https://github.com/devfile/api/issues/22[Renaming workdir into workingDir]
* link:https://github.com/devfile/api/issues/18[Id and label for composite commands]
* 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]
37 changes: 11 additions & 26 deletions docs/modules/user-guide/partials/proc_migrating-components.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@
= 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.
This section describes how to migrate components to v2.x devfiles. A component specified in a v1.x devfile no longer works in a v2.x devfile.

.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`.
The validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin`, or `volume`.
+
[source,yaml]
----
Expand All @@ -26,32 +26,17 @@ 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

For more information on migrating components, go to the following GitHub issues:

* 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].
* 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]
12 changes: 6 additions & 6 deletions docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
= 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 a v2.x devfile. A plug-in specified in a `meta.yaml` for a v1.x devfile no longer works in a v2.x devfile.

Additionally, v2.x devfiles include the following new features:

Expand All @@ -13,9 +13,9 @@ Additionally, v2.x devfiles include the following new features:
[role="_additional-resources"]
.Additional resources

To learn more about plug-ins in v2.x devfiles, go to the GitHub issues on the following topics:
For more information on plug-ins in v2.x devfiles, go to the following GitHub issues:

* 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].
* link:https://github.com/eclipse/che/issues/18669[Devfile plug-ins not suited to specify Che-Theia plug-ins]
* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plug-ins support in v2.x devfile]
* link:https://github.com/devfile/api/issues/364[Plug-ins' replacement]
* link:https://github.com/devfile/api/issues/31[Better plug-in mechanism]
11 changes: 5 additions & 6 deletions docs/modules/user-guide/partials/proc_migrating-projects.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,25 @@
= 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 v2.x devfiles. A project specified in a v1.x devfile still works in a v2.x devfile.

.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).
+
A new `starterProject` project type can be defined in v2.x devfiles. 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.

.starterProjects and projects description
====
[source,yaml]
----
v2.0
---
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"
----
====

[role="_additional-resources"]
.Additional resources
* See link:https://github.com/che-incubator/devworkspace-api/issues/42[corresponding issue].

For more information on migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
= Migrating schema version

[role="_abstract"]
This section describes how to migrate schema version.
This section describes how to migrate the existing schema version to a v2.x devfile. The schema version specified in a v1.x devfile still works in a v2.x devfile.

.Procedure

* Replace `apiVersion: 1.0.0` by `schemaVersion: 2.0.0`:

. To migrate a schema version from a v1.x devfile to a v2.x devfile, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`:
+
[cols="1a,1a"]
|====
|
Expand All @@ -29,9 +29,9 @@ metadata:
name: devfile-sample
----
|====


+

[role="_additional-resources"]
.Additional resources
* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue]

For more information on migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].
Original file line number Diff line number Diff line change
@@ -1,18 +1,23 @@
[id="proc_refering-to-a-parent-devfile-in-a-devfile_{context}"]
= Refering to a parent devfile in a devfile
= Referring to a parent devfile in a devfile

[role="_abstract"]
It is possible to refer to another devfile as a parent to a given devfile. If a parent is specified, the devfile will inherit all behaviour from the parent. Part of the content of the parent can be overridden in the child devfile. That allows refering a devfile (the parent) from a distinct devfile and makes it possible to reuse in multiple devfiles the same parent (the stack).
This section describes how to designate a parent devfile to a given devfile. If you designate a parent devfile, the given devfile inherits all its behavior from its parent. Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles.

.Prerequisites

* xref:adding-schema-version-to-a-devfile.adoc[]
* xref:adding-a-name-to-a-devfile.adoc[]
* Define the `schemaVersion` to v2.x. If you need to define your `schemaVersion`, go to xref:adding-schema-version-to-a-devfile.adoc[].
* Define a name for the devfile. If you need to define a name for your devfile, go to xref:adding-a-name-to-a-devfile.adoc[].


.Procedure

* A parent devfile can be referenced in 3 different ways: `registry`, `uri` or `kubernetes`.
You can refer to a parent devfile in three different ways:

* `registry`
* `uri`
* `kubernetes`

+
.Parent referred by registry
====
Expand Down Expand Up @@ -62,5 +67,7 @@ parent:
[role="_additional-resources"]
.Additional resources

For more information on referring to parent devfiles, go to the following topics:

* xref:api-reference.adoc[]
* xref:devfile-samples.adoc[]