Provide FAQ / Known issues / Troubleshooting for devfile v1 -> devfile v2 convertion

[ibuziuk]

Is your task related to a problem? Please describe

With the switch to the DevWorkspace engine, devfile v2 becomes a default format for workspace definition. Need to provide clear documentation for conversion of devfile v1 devfile v2 and publish it on the https://www.eclipse.org/che/docs
Probably it also makes sense to publish a blog post at https://che.eclipseprojects.io/

Describe the solution you'd like

Clear documentation for devfile v1 -> devfile v2 convertion

Describe alternatives you've considered

There is already migration documentation that is part of the https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html

As an alternative, we can just fall back on to the official devfile docs. Which would probably be the best approach

Additional context

Related to #20845

[ibuziuk]

cc: @themr0c is che-docs team initial creator and supporter of https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html ?

[benoitf]

@l0rd seems to be the creator https://github.com/devfile/docs/commits/8a4ae3ceda1695fa8caced9c65ad10971bffab2f/docs/modules/ROOT/pages/migration_guide.adoc

[themr0c]

@ibuziuk In the devfile documentation project, I only helped to set up things and migrate initial content from che-docs. The project is in the hands of other people from the DevTools Docs team: @rkratky as Content Strategist, and @jc-berger as main writer.

[rkratky]

@ibuziuk, I'd suggest falling back on the devfile docs whenever possible. If the existing migration docs need modifying, please open an issue in that repo - we'll pick it up.

[themr0c]

The existence of the devfile-converter library [1] is probably worth mentioning in devfile docs [2].
[1] https://www.npmjs.com/package/@eclipse-che/devfile-converter
[2] https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html

-> devfile/api#722

[ibuziuk]

@themr0c I doubt that customers will be using an internal lib for conversion.

I agree that we need to fall back on https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html though.
Basically, someone needs to meticulously review the docs and contribute if there are some missing bits.
@benoitf maybe you can give a hand with this since you know all the details and edge cases that are covered as part of the https://github.com/che-incubator/devfile-converter ?

[themr0c]

What would make sense in che-docs is a procedure "Using the Dashboard to convert a devfile" explaining only the Che specific stuff, with the Additional resources section pointing to https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html. Maybe also "Using the Che-Theia IDE to convert a devfile"?

[themr0c]

Basically, someone needs to meticulously review the docs and contribute if there are some missing bits.

Fully agree!

[ibuziuk]

The current plan discussed on the Cabal call is to provide FAQ / Known issues to https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html

[ibuziuk]

@rkratky could you clarify why https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html is 404 now and we only have 2.2.0 alpha docs available - https://devfile.io/docs/devfile/2.2.0/user-guide/migrating-to-devfile-v2/ ?

[rkratky]

@ibuziuk, that's a bug (since yesterday's republication), and we're working on fixing it.

[rkratky]

@ibuziuk, the bug is fixed: https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2/

(Note that URL does not have '.html' at the end.)

[ibuziuk]

@rkratky https://devfile.io/docs/devfile/2.1.0/user-guide/migrating-to-devfile-v2.html still 404 🤷‍♂️

[benoitf]

Here are some points to add about Troubleshooting for devfile v1 --> devfile v2

1. Main point is that Che-Theia editor will inject by default all their plug-ins into a 'user-defined' container.
   If the devfile v1 contains at least one container component then it's in pretty good shape to work.
   if there is no component with one container it'll fail.

This limitation should be fixed when devfile/devworkspace-operator#656 will be implemented. Because the editor definition will contain a default component to add in the devfile.

2. Needs to check that the 'user container' is a valid container for starting Theia endpoint inside (it'll change the entrypoint of the container). Once Extend the DevWorkspaceTemplate spec with containers contributions devfile/devworkspace-operator#656 is implemented, it'll use the post-start container event to run the editor endpoint.

[benoitf]

if the startup fails, it may be good to try to use a universal developer image as the only component

it should allow to boot the workspace properly

components:
  - name: tools
    container:
      image: quay.io/devfile/universal-developer-image:ubi8-latest
      memoryLimit: 3Gi

[benoitf]

and also if the current user container is not working with plug-ins being executed there

It's possible for che-theia to apply an attribute
che-theia.eclipse.org/sidecar-policy

default value is 'use dev container' but to use 'sidecar container as before mergeImage as value of the attribute should be set.

https://github.com/eclipse-che/che-theia/blob/main/tools/devworkspace-handler/src/devfile/che-theia-plugins-devfile-resolver.ts#L113-L119

[benoitf]

I've also created an issue that may help:

• Allow to boot a workspace in rescue mode #21335

[ibuziuk]

PR with troubleshooting guide is ready for review - devfile/docs#153