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 5 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
9 changes: 5 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,7 @@ endif::[]

:context: assembly_migrating-to-devfile-v2

This guide explains how to migrate an existing v1.0 devfile to v2.0.
This guide explains how to migrate an existing devfile v1.x to a devfile v2.x.

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

13 changes: 5 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,8 @@ events:
- pre-compile-cmd
----
====

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

Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands]
35 changes: 19 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,36 @@
= 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.
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.

.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].
Go to the following GitHub issues:

* 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]
37 changes: 11 additions & 26 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,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 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.

.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`.
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`.
+
[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

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]
32 changes: 17 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,13 @@
= 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.
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.

.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 +27,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 +58,25 @@ 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].

Go to the following GitHub issue: link:https://github.com/devfile/api/issues/31[plug-in mechanism]
12 changes: 7 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,14 @@
= 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).
+
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.

.starterProjects and projects description

====
[source,yaml]
----
Expand All @@ -18,10 +19,11 @@ 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].

Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
12 changes: 6 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,9 @@ metadata:
name: devfile-sample
----
|====


+

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

Go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].
27 changes: 19 additions & 8 deletions ...modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,27 @@
= Refering 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).
You can designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent.

.Prerequisites

* xref:adding-schema-version-to-a-devfile.adoc[]
Copy link

Choose a reason for hiding this comment

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

in our guides we use descriptive sentences of the prerequisites and then link to other chapters in case further information is needed. Not sure about the standards here, but as a user it would be good to understand at a glance if the prerequisite is met or not.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Let me know what you think about the abstract I wrote...I feel like it's too repetitive of the information right below it.

* xref:adding-a-name-to-a-devfile.adoc[]


This section describes how to specify a parent devfile. You can choose a devfile and refer to another devfile as its parent. If you specify a parent, the child devfile inherits all its behavior from its parent devfile. 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.

.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
====
Using its `id` if it has been published in a registry.
Use the `id` if it has been published in a registry.

[source,yaml]
----
Expand All @@ -28,24 +34,29 @@ parent:
registry: https://devfile-registry.io/
----
====
+

.Parent referred by uri
====
Using the URI if it has been published on a static http server (like gist or pastebin).
Use the URI if it has been published on a static http server like gist or pastebin.

[source,yaml]
----
schemaVersion: 2.0.0
metadata:
name: my-project-dev
parent:
<<<<<<< HEAD
uri: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml
=======
id: redhat/nodejs/11.6
uri: https://raw.githubusercontent.com/devfile/registry/master/stacks/nodejs/devfile.yaml
>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide
----
====
+

.Parent identified by a Kubernetes resource
====
Using a Kubernetes resource name and namespace if it has been deployed on a Kubernete cluster.
Use a Kubernetes resource name and namespace if it has been deployed on a Kubernetes cluster.

[source,yaml]
----
Expand Down