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 1 commit
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
2 changes: 1 addition & 1 deletion 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 @@ -24,7 +24,7 @@ This guide explains how to migrate an existing devfile v1.x to a devfile v2.x.
[role="_additional-resources"]
.Additional resources

For a deeper understanding of migrating devfiles, go to the GitHub issues on the following topics:
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]
Expand Down
16 changes: 1 addition & 15 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,15 +2,7 @@
= Adding event bindings

[role="_abstract"]
<<<<<<< HEAD
Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`.
=======
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.
>>>>>>> d8b8834... more tweaks for consistent devfile versioning
.Prerequisites
Add an `events` section in your devfile and make sure it contains a list of `preStart` and `postStart` commands.

.Procedure

Expand Down Expand Up @@ -50,11 +42,5 @@ events:
+
[role="_additional-resources"]
.Additional resources
<<<<<<< HEAD
* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue].
=======

For a deeper understanding of adding events, go to the GitHub issue on the following topic:

* link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands]
>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide
Go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[Lifecycle bindings to bind commands]
4 changes: 2 additions & 2 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,7 +2,7 @@
= Migrating commands

[role="_abstract"]
This section describes how to migrate commands to devfiles v2.x. The command section of devfile v2.x has major changes. 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.

.Procedure

Expand All @@ -18,7 +18,7 @@ This section describes how to migrate commands to devfiles v2.x. The command sec
[role="_additional-resources"]
.Additional resources

For a deeper understanding of migrating commands, go to the GitHub issues on the following topics:
Go to the following GitHub issues:

* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug]

Expand Down
62 changes: 9 additions & 53 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,23 +2,14 @@
= Migrating components

[role="_abstract"]
This section describes how to migrate components to devfiles v2.x. The components section of devfiles v2.x has major changes. 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.

.Procedure

<<<<<<< HEAD
<<<<<<< HEAD
. 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`.
+
=======
. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
=======
. To get a better syntax validation, define a component as a polymorphic type and implement it as a `container`, `kubernetes`, `openshift`, `plug-in` or `volume`.
>>>>>>> d8b8834... more tweaks for consistent devfile versioning
+
>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide
[source,yaml]
----
v2.0
Expand All @@ -34,53 +25,18 @@ components:
- kubernetes:
uri: https://.../mongo.yaml
----
<<<<<<< HEAD
+
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].


=======
+
>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide
[role="_additional-resources"]
.Additional resources

For a deeper understanding of migrating components, go to the GitHub issues on the following topics:
Go to the following GitHub issues:

<<<<<<< HEAD
<<<<<<< HEAD
* 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[Component is a polymophic type]
=======
* link:https://github.com/devfile/api/issues/4[Component is a polymorphic type]
>>>>>>> d8b8834... more tweaks for consistent devfile versioning
* 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 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[Renaming dockerimage component type]
* link:https://github.com/devfile/api/issues/17[Specify sources path for containers]
* link:https://github.com/devfile/api/issues/14[Specify size of volume for component]
* link:https://github.com/devfile/api/issues/33[Containers endpoints: routes and ingresses]
>>>>>>> c68d47f... brought back the procedures, updated links, more changes to content for consistency and style guide
* 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]
6 changes: 2 additions & 4 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,7 +2,7 @@
= Migrating plug-ins

[role="_abstract"]
This section describes how to migrate plug-ins to devfiles v2.x. The plug-ins section of devfile v2.x has major changes. 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.

.Procedure

Expand Down Expand Up @@ -79,6 +79,4 @@ components:
[role="_additional-resources"]
.Additional resources

For a deeper understanding of migrating plug-ins, go to the GitHub issue on the following topic:

* 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]
5 changes: 2 additions & 3 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 @@ -6,7 +6,7 @@ This section describes how to migrate projects to devfiles v2.x. A project speci

.Procedure

A major change in devfiles v2.x is the addition of a new kind of project: `starterProjects`. You should only pick one `starterProject` and only use this project in interactive mode. Also, you only need to copy your source code. You no longer need to clone your git repo.
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

Expand All @@ -25,6 +25,5 @@ starterProjects:

[role="_additional-resources"]
.Additional resources
For a deeper understanding of migrating projects, go to the GitHub issue on the following topic:

* link:https://github.com/devfile/api/issues/42[StarterProjects]
Go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
3 changes: 1 addition & 2 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 @@ -33,6 +33,5 @@ metadata:

[role="_additional-resources"]
.Additional resources
For a deeper understanding of migrating schema versions, go to the GitHub issue on the following topic:

* 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].
16 changes: 9 additions & 7 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,25 +2,27 @@
= Refering to a parent devfile in a devfile

[role="_abstract"]
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

@Eva-Lotte Eva-Lotte Mar 31, 2021

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

@jc-berger jc-berger Apr 8, 2021

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 teaches you 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.
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

You can refer to a parent devfile in three different ways:

. registry
. uri
. kubernetes
* 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 @@ -35,7 +37,7 @@ parent:

.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]
----
Expand All @@ -54,7 +56,7 @@ parent:

.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