Add documentation for migration to Vue3 for Rancher Extensions

[cnotv]

Description

As part of the update efforts to Vue3, create documentation for Rancher Extensions authors on how to migrate.

• Add introduction
• Add further steps for Rancher Extensions to the existing docs
• Add issue handling for uncovered parts
• Add further notes as outcome of https://github.com/rancher/dashboard/issues/11049
• Typescript to be handled with https://github.com/rancher/dashboard/issues/10871

Notes

Breaking changes

Template tags with no special directives

We need to specifically call out the breaking change involving template tags with no special directives^1. We've encountered this several times throughout the Dashboard codebase and extension authors should be made aware as well.

<template> tags with no special directives (v-if/else-if/else, v-for, or v-slot) are now treated as plain elements and will result in a native <template> element instead of rendering its inner content.

Symptoms

• Template content does not render on page

Causes

• Template tags nested in a component with no special directives. Example

  <template>
   <h1>My Component</h1>
   <template>
     <!--content within this nested template will not render-->
     <AlertTable
       :monitoring-namespace="monitoringNamespace"
       :alert-service-endpoint="alertServiceEndpoint"
     />
   </template>
  </template>

• Template tags that listen to events. Example:

  <template>
   <h1>My Component</h1>
   <template @update:value="update">
     <!--content within this nested template will not render and the listener will need to be attached to the inner component-->
     <LabeledInput
       v-model:value="value.httpGet.httpHeaders[index].name"
       :label="t('workload.container.lifecycleHook.httpHeaders.name.label')"
       :placeholder="t('workload.container.lifecycleHook.httpHeaders.name.placeholder')"
       class="single-value"
       :mode="mode"
       required
     />
   </template>
  <template>

Attributes binding

The $listeners object has been removed in Vue 3. Event listeners are now part of $attrs ^2

This clashes with multiple cases where we bind the attributes to the component. As a consequence, the event listener has to be defined ^3.

(Thanks @rak-phillip for finding, reporting, and documenting)

Dynamically loaded components

In cases where we are importing components from extensions, this has to be added dynamically. Currently, this aspect falls into Dashboard code only, although it's important to make it clear.

[cnotv]

As defined in the meeting, we'll have to add in the documentation for internal and external use:

• @rak-phillip to list roadblocks encountered while performing the minimal viable Vue3 experiment
• @cnotv to list known challenges in configs and initialization process
• @codyrancher to list known any remaining Nuxt removal related challenges that we might have (middleware, routing, anything else?)

[richard-cox]

For Breaking change: template tags with no special directives We should specifically call out that this might affect custom edit components and signs to watch out for when it does (as in the common causes for why we're sticking them in our edit components)

[cnotv]

@rak-phillip could we add this as a case for the template? https://github.com/rancher/dashboard/pull/11902/files#diff-af7c5762776e76054d7291bddd3e89ff397e95e3c053a7dd4b12402d553f72e7L188

[rak-phillip]

That's definitely an edge case and I'm surprised that it was even working on the first place.. but, of course, we can add a note to address this.

[cnotv]

Bumping milestone as planned for extensions.

[richard-cox]

This is very much needed for 2.10.0 to support both internal and external extension developers.

[cnotv]

Could you give me the list of who is missing internally? Are we communicating with internal or external about the change to Vue3? Which chat? I have been cut out from this whole process, and the last update was that we are going to update the extensions after 2.10. Has this changed?

In any case, I've to take a look with @jordojordo about this, as I may not be aware of the process they have been using for Harvester, Elemental, and Kubewarden.

[richard-cox]

Could you explain what you mean by missing? Nothing has changed though, prime extensions will come in 2.10.1.

I'm not involved with the communication, though externally it has started via https://extensions.rancher.io/extensions/rancher-2.10-support and internally direct contact with known extension owners.

Bottom line external extension developers will want this guide from 2.10.0, and internal developers before 2.10.1

[cnotv]

Bottom line external extension developers will want this guide from 2.10.0, and internal developers before 2.10.1

External developers cannot get it before the internal ones, for the simple fact that we do not know the encountered issues, which is the scope of the guide and is against the Vue3 planning.

[cnotv]

I still have not received any feedback from anyone in this issue, except for what we can read above, so I will stick to that as I have no information whatsoever. After this, we may want to extend it to other cases which we consider relevant. If you think we should insert something more, please just list it down or specify, as I have not been informed.

[richard-cox]

@cnotv External extension developers will want their extensions working in 2.10.0. The guide is designed to help them update their extensions to do so.

Releasing the docs in 2.10.1 will not help them. TBH we should already have created them so they can be ready before 2.10.0 is released.

If you are unsure on the issues the Vue3 migration has created, or about the extension mechanism, please leave this one for someone else.

[cnotv]

What, when, and how this documentation has to be updated has been written since March 20. There has not been anything collected here as requested. Therefore, I leave it to someone else as it seems there's someone better as you suggest.

[jordojordo]

@aalves08 and I have been working on this in the background, we have notes elsewhere that I will consolidate into our documentation.

[cnotv]

Change of libraries due Nuxt removal is also another topic https://github.com/rancher/ui-plugin-examples/blob/main/pkg/clock/package.json#L22-L23