Skip to content

WIP: made migrating docs adhere to style guide #39

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.

Sign up for GitHub

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

Closed
wants to merge 13 commits into from
Closed

WIP: made migrating docs adhere to style guide #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8ac2ff8
made migrating docs adhere to style guide
Jan 28, 2021
5ac121b
brought back the procedures, updated links, more changes to content f…
Mar 12, 2021
ff05d0c
more tweaks for consistent devfile versioning
Mar 29, 2021
4caff9d
fixed merge conflicts
Apr 6, 2021
f72a9ee
Update devfile schema based on devfile/api@a313872749ed60b47fb015288b…
davidfestal Apr 8, 2021
6471455
addressed doc review
Apr 8, 2021
f5c22d3
made migrating docs adhere to style guide
Jan 28, 2021
155d6ec
brought back the procedures, updated links, more changes to content f…
Mar 12, 2021
1a06eb0
more tweaks for consistent devfile versioning
Mar 29, 2021
fbfe349
fixed merge conflicts
Apr 6, 2021
d1d03ef
addressed doc review
Apr 8, 2021
5c5ec99
more doc changes
Apr 9, 2021
72fa0cd
more doc changes
Apr 12, 2021
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
1,219 changes: 0 additions & 1,219 deletions docs/modules/user-guide/attachments/jsonschemas/next/devfile.json
View file
Open in desktop

Large diffs are not rendered by default.

17 changes: 13 additions & 4 deletions docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand All @@ -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:]

17 changes: 9 additions & 8 deletions docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand Down Expand Up @@ -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
43 changes: 27 additions & 16 deletions docs/modules/user-guide/partials/proc_migrating-commands.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,44 @@
= 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.
<<<<<<< HEAD
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.
=======
This section describes how to migrate commands to devfiles v2.x. Major changes have been made from devfiles v1.x to the command section of devfile v2.x. A command specified in a devfile v1.x no longer works in a devfile v2.x.
>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4

.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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it clear to the reader how to command groups? I don't understand this step^^

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this doc needs major revisions which we've discussed in previous PRs. We'll tackle these concerns in the separate issue for properly structure our procedures: devfile/api#402

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is this paragraph supposed to do?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should it really list enumerated steps to follow?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my response in your previous comment.

. Apply command.
. Environment variables for a specific command.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a step in a procedure. Should this paragraph be a procedure in the first place?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my response in your previous comment.

. 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 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].
<<<<<<< HEAD
For a deeper understanding of migrating commands, go to the following GitHub issues:
=======
Go to the following GitHub issues:
>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4

* Environment Varibables 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/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]
51 changes: 24 additions & 27 deletions docs/modules/user-guide/partials/proc_migrating-components.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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]
40 changes: 25 additions & 15 deletions docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,17 @@
= 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.
<<<<<<< HEAD
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.
=======
This section describes how to migrate plug-ins to devfiles v2.x. Major changes have been made from devfile v1.x to the plug-ins section of devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x.
>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4

.Procedure

. 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.
. Specify a plug-in using a devfile.

+
[source,yaml]
----
v2.0
Expand All @@ -26,12 +31,12 @@ metadata:
repository: https://github.../vscode-java
category: Language
firstPublicationDate: "2020-02-20"
pluginType: che-theia-vsx # <== mandatory
# for plugins
# Valid types:
plug-inType: che-theia-vsx # <== mandatory
# for plug-ins
# Valid types:
# che-theia-vsx
# che-editor,
# che-theia-plugin,
# che-editor,
# che-theia-plug-in,
# che-theia-ext,
# generic-service,
# generic-ui
Expand All @@ -57,24 +62,29 @@ components:
- volume:
name: m2
----

. And then can be referenced from a distinct devfile:

+
. Reference a plug-in from a distinct devfile.
+
[source,yaml]
----
v2.0
---
devfile.yaml
---
components:
- plugin:
- plug-in:
name: java language server
id: redhat/java11/0.57.0 # other then by `id`, a plugin
# can be referenced by `uri` and
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
* See https://github.com/che-incubator/devworkspace-api/issues/31[corresponding issue].

<<<<<<< HEAD
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].
=======
Go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism]
>>>>>>> 6471455677b28b0e892adc4c24e14acfc17678a4
20 changes: 15 additions & 5 deletions docs/modules/user-guide/partials/proc_migrating-projects.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -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
16 changes: 10 additions & 6 deletions docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
View file
Open in desktop
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 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`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where do I need to go to replace the schema version? Do you change a section in the devfile? This should be more clear I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I don't know the answer. It's probably something we can tackle in the separate issue for properly structure our procedures: devfile/api#402

+
[cols="1a,1a"]
|====
|
Expand All @@ -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
Loading