Extensions docs update (#12491)

* update docs with migration guide + new mechanism to fix annotations + other small changes

* Update docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

Co-authored-by: Jordon Leach <[email protected]>

* update docs for annotations fix + update dates format on changelog + fix link on homepage

* configure redirect plugin (only works in production)

* update redirect config

* Update docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

Co-authored-by: Jordon Leach <[email protected]>

* Update docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

Co-authored-by: Jordon Leach <[email protected]>

* Update docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

Co-authored-by: Jordon Leach <[email protected]>

* Update docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

Co-authored-by: Jordon Leach <[email protected]>

* hide docs on fixing annotations

* add simple change to re-trigger test

---------

Co-authored-by: Jordon Leach <[email protected]>

cypress/e2e/tests/pages/explorer/apps/repositories.spec.ts

@@ -1,3 +1,4 @@
+//
 import ReposListPagePo from '@/cypress/e2e/po/pages/chart-repositories.po';
 import AppClusterRepoEditPo from '@/cypress/e2e/po/edit/catalog.cattle.io.clusterrepo.po';
 import { ChartPage } from '@/cypress/e2e/po/pages/explorer/charts/chart.po';

docusaurus/docs/extensions/advanced/fix-annotations-published-extensions.md

@@ -0,0 +1,31 @@
+# Fixing annotations on published extensions
+
+As the development of an extension progresses over time, through different versions of Rancher and the Shell package, some users may wonder why a specific extension version is available for installation in Rancher versions when it is known that it shouldn't work.
+
+This is due to the fact that when the first releases were done, no-one could foresee if future versions would have breaking changes, therefore [annotations](../extensions-configuration#configurable-annotations) most commonly used like `catalog.cattle.io/rancher-version` or `catalog.cattle.io/kube-version` would either lack an upper limit boundary or just have too low of an upper limit.
+
+Since that extension was already built and served to users, fixing annotations and repackaging an extension my be a pain point that would often get postponed.
+
+Starting with Shell version `3.0.0`, we have introduced a feature that allows developers to update annotations on published extension versions. This mechanism enables changes to persist in the `index.yaml` file over time and ensures that the `tgz` assets are re-packaged with the correct annotations (GitHub only). To leverage this mechanism, developers should follow this procedure:
+
+**1)** Copy over the contents of the root file `package.json` to have access to the yarn command alias `publish-pkgs`. You'll need to create the file in the branch where the Helm chart that serves your extension lives in.
+
+**2)** After identifying which extension version you want to fix the annotations for, go to branch of the repository where the Helm chart that serves your extension lives (for the examples we [provide](./../extensions-getting-started.md#creating-a-release) that branch should be `gh-pages`) and edit the `Chart.yaml` in `charts/<-YOUR-EXT->/<-EXT-VERSION-TO-FIX->/Chart.yaml` and change the annotations there as desired
+
+**3)** On the same branch, create on the root a file called `package.json`, with the contents copied from step 1)
+
+**4)** Install node modules by running `yarn install`
+
+
+**5)** In the root of your branch, run the following command:
+```js
+yarn publish-pkgs -e -s <-GITHUB-ORG->/<-GITHUB-REPO->
+```
+
+In the case of the [Elemental repo](https://github.com/rancher/elemental-ui), the `GITHUB-ORG` would be `rancher` and `GITHUB-REPO` would be `elemental`
+
+This will update the `index.yaml` of your Helm chart, propagating those annotation changes and also re-package the `tgz` file under `assets`.
+
+**6)** Once the procedure is complete, remove the `package.json`, `yarn.lock`, and `/node_modules` folder from your branch to avoid committing them.
+
+**7)** Create a pull request for your repository and merge your changes. The annotations for the published version should now reflect your updates.

docusaurus/docs/extensions/changelog.md

@@ -8,11 +8,12 @@
 
 | Date | Version | Description |
 |---|---|---|
-| 09‑07‑2024 | 1.2.3 | Minor bug fixes |
-| 09‑07‑2024 | [**2.0.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.1) | Minor bug fixes |
-| 01‑07‑2024 | 1.2.2 | First release of a new `Shell` version, but codewise similar to `0.5.3` in order to keep extensions api versioning up to par with shell versioning |
-| 01‑07‑2024 | [**2.0.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.0) | Various fixes to the `Shell` package in order to make it compliant with Rancher 2.9 |
-| 15‑02‑2024 | [**0.5.3**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.3) | Inclusion of the replacement of `Vue.extend` to `defineComponent` with proper fix |
-| 31‑01‑2024 | [**0.5.2**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.2) | Fix `parse tag name` check in workflows for publishing extensions |
-| 29‑01‑2024 | [**0.5.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.1) | Revert changes to replacement of `Vue.extend` to `defineComponent` because of impact on extensions |
-| 24‑01‑2024 | [**0.5.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.0) | Add support for Gitlab workflows for publishing extensions |
+| 01 November 2024 | [**2.0.2**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.2) | Remove upper limit on kube version for default annotations on extensions. Update creators package. Minor bug fixes |
+| 09 July 2024 | 1.2.3 | Minor bug fixes |
+| 09 July 2024 | [**2.0.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.1) | Minor bug fixes |
+| 01 July 2024 | 1.2.2 | First release of a new `Shell` version, but codewise similar to `0.5.3` in order to keep extensions api versioning up to par with shell versioning |
+| 01 July 2024 | [**2.0.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.0) | Various fixes to the `Shell` package in order to make it compliant with Rancher 2.9 |
+| 15 February 2024 | [**0.5.3**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.3) | Inclusion of the replacement of `Vue.extend` to `defineComponent` with proper fix |
+| 31 January 2024 | [**0.5.2**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.2) | Fix `parse tag name` check in workflows for publishing extensions |
+| 29 January 2024 | [**0.5.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.1) | Revert changes to replacement of `Vue.extend` to `defineComponent` because of impact on extensions |
+| 24 January 2024 | [**0.5.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.0) | Add support for Gitlab workflows for publishing extensions |

docusaurus/docs/extensions/home.md

@@ -6,4 +6,4 @@ Extensions can be created independently of Rancher and their code can live in se
 
 You can find some example extensions here: https://github.com/rancher/ui-plugin-examples
 
-> Note: Rancher Extensions is in early development - support for Extensions was recently added to Rancher 2.7.0 and the internal Rancher team is building out extensions using the extensions framework. Over time, the extensions API will improve and the supporting documentation will be built out, to enable the wider developer community to build their own extensions.
+**With the upcoming release of Rancher v2.10, we have introduced a new version of the Rancher Extensions documentation (v3), along with a migration guide to help get your extension compliant with Rancher v2.10 since we've moved from Vue2 to Vue3. Learn more about it [here](./rancher-2.10-support.md).**

docusaurus/docs/extensions/known-issues.md

@@ -1,5 +1,7 @@
 # Known issues
 
+## For Shell v1 and v2
+
 - Running `yarn install` might throw the following error:
 ```
 error [email protected]: The engine "node" is incompatible with this module

docusaurus/docs/extensions/rancher-2.10-support.md

@@ -1,11 +1,95 @@
 # Rancher 2.10.0 update
 
-## Advance Notice
+## Breaking Changes in 2.10.0
 
-The Rancher UI, the Shell and the UI Extensions mechanism is being updated from the Vue 2 framework to the Vue 3 framework.
+Following the updates to the Rancher UI, Shell package, and the UI Extensions from Vue2 to Vue3, we have introduced breaking changes to the UI Extensions. These changes require you to update your existing extensions in order to be compliant with the Rancher `2.10` UI framework.
 
-This is a breaking change that will require existing Rancher UI Extensions to be migrated to Vue 3, built and published.
+## How to proceed with your extension update
 
-Our intent is to provide migration documentation to assist UI Extension authors in this migration.
+We have developed a migration script that will allow extension developers to easily migrate their extensions to the minimum required setup in order to be compliant with this breaking change.
 
-More information will be available as development progresses.
+Notably we update the Shell package to version `3.x.x`, which is now a requirement to be compliant with Rancher `2.10`, but we also update some of the core files of you app skeleton in order to be compatible with the new node version now in use `v20`. To find out more about the support matrix for Shell versions in regards to Rancher versions, check the support matrix [here](./support-matrix#shell-support-matrix).
+
+On top of this, the migration script also does some of the basic changes in terms of syntax needed to work with Vue3. However, please note that this feature is **experimental** and therefore **unsupported** for syntax migration. We recommend familiarizing yourself with the differences between Vue2 and Vue3 by following the official documentation [here](https://v3-migration.vuejs.org/).
+
+To make use of this migration script, you'll just need to run the following command on the root folder of your skeleton app that contains your extensions:
+
+```sh
+yarn create @rancher/extension --migrate [OPTIONS]
+```
+
+### **_Migration script options_**
+
+There are a few options available to be passed as an argument to the `@rancher/extension --migrate` script:
+
+|          Option           | Description                                                                                                                                                                                                                                                                             |
+| :-----------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|     `--dry`      | Dry Run Mode: Run the script without making any changes to your files.                                                    |
+|     `--verbose`      | Verbose Output: Enable detailed logging.                                                    |
+|     `--suggest`      | Suggest Mode: Generate a 'suggested_changes.diff' file with proposed changes.                                                    |
+|     `--paths=<path>`      | Specify Paths: Limit migration to specific paths or files (accepts glob patterns).                                                    |
+|     `--ignore=<patterns>`      | Ignore Patterns: Exclude specific files or directories (accepts comma-separated glob patterns).                                                    |
+|     `--files`      | Output Modified Files: List all files modified during the migration.                                                    |
+|     `--log`      | Generate Log File: Write detailed migration statistics to 'stats.json'.                                                    |
+|     `--help, -h `      | Display this help message and exit.                                                    |
+
+---
+
+## Notable Vue3 syntax changes
+
+These are the most common Vue3 syntax changes that you may encounter on your extensions:
+
+- `v-model` usage update: https://v3-migration.vuejs.org/breaking-changes/v-model.html
+- `key` usage change: https://v3-migration.vuejs.org/breaking-changes/key-attribute.html
+- `v-bind` merge behaviour: https://v3-migration.vuejs.org/breaking-changes/v-bind.html
+- Async components: https://v3-migration.vuejs.org/breaking-changes/async-components.html
+- Slots Unification: https://v3-migration.vuejs.org/breaking-changes/slots-unification.html
+- `$attrs` includes `class` & `style`: https://v3-migration.vuejs.org/breaking-changes/attrs-includes-class-style.html
+- Attribute Coercion Behavior: https://v3-migration.vuejs.org/breaking-changes/attribute-coercion.html#attribute-coercion-behavior
+- Inline Template Attribute: https://v3-migration.vuejs.org/breaking-changes/inline-template-attribute.html#inline-template-attribute
+
+## New mandatory annotation
+
+One of the new changes that we've introduced is that for a published extension to be loaded into a Rancher `2.10` system, the published helm chart for a particular version **must** include the `catalog.cattle.io/ui-extensions-version` annotation, being the minimum version needed `>= 3.0.0`.
+
+We also recommend that you update the `catalog.cattle.io/rancher-version` to `>= 2.10.0`.
+
+You should check that your extension `pkg/<-YOUR EXTENSION->/package.json` shows something similar to:
+
+```json
+{
+  "name": "your-extension",
+  "description": "your-extension description",
+  "version": "1.2.1",
+  "rancher": {
+    "annotations": {
+      "catalog.cattle.io/rancher-version": ">= 2.10.0",
+      "catalog.cattle.io/ui-extensions-version": ">= 3.0.0"
+    }
+  },
+  ....
+}
+```
+
+## How to maintain different extension versions
+
+In terms of development procedure, we recommend branching your extension repository to manage compatibility with both Rancher 2.9 and Rancher 2.10, if your extension is impacted by version-specific changes.
+
+You can check the example of `Elemental` where branch `main` is tracking the **Rancher 2.10 compliant version** and `release-2.9.x` branch is tracking everything Rancher "2.9".
+
+The difference between the two branches are some annotations and of course the shell versions being used.
+
+`main`
+- https://github.com/rancher/elemental-ui/blob/main/pkg/elemental/package.json#L6-L12
+- https://github.com/rancher/elemental-ui/blob/main/package.json#L10
+
+vs `release-2.9.x`
+- https://github.com/rancher/elemental-ui/blob/release-2.9.x/pkg/elemental/package.json#L6-L12
+- https://github.com/rancher/elemental-ui/blob/release-2.9.x/package.json#L11
+
+
+The workflow we offer for Github to build and release extensions to the `gh-pages` branch https://extensions.rancher.io/extensions/publishing#triggering-a-github-workflow-on-tagged-release will work just fine, but when doing a tagged release you’ll need to mindful of the target branch you want to release from.
+
+![Release target branch](./screenshots/target-branch.png)
+
+Picking up on the Elemental example, to release a Rancher 2.9 compliant version, we would need to target the `release-2.9.x` branch (with the appropriate tag format ex: `elemental-1.3.1-rc9` which is `extensionName-extensionVersion` ) and for Rancher 2.9 you would target the `main` branch as one would normally do in an extension release. We recommend that you don’t trigger both releases at the same time (let one finish first, then trigger the other release).

docusaurus/docs/extensions/support-matrix.md

@@ -7,10 +7,10 @@ It's important to know which version of the Shell package is compatible with eac
 
 | | Rancher 2.7.x | Rancher 2.8.x <br/> (Extensions API V1) | Rancher 2.9.x <br/> (Extensions API V2) | Rancher 2.10.x <br/> (Extensions API V3) |
 |---|---|---|---|---|
-|Shell **0.3.8**|Supported|Limited support|Not supported|Not supported|
-|Shell 0.5.3/**1.2.3**|Limited support|Supported|Not supported|Not supported|
-|Shell **2.0.1**|Not supported|Not supported|Supported|Not supported|
-|Shell **3.0.0**|Not supported|Not supported|Not supported|Supported|
+|Shell **0.3.8**|**Supported**|Limited support|Not supported|Not supported|
+|Shell 0.5.3/**1.2.3**|Limited support|**Supported**|Not supported|Not supported|
+|Shell **2.0.1**|Not supported|Not supported|**Supported**|Not supported|
+|Shell **3.0.0**|Not supported|Not supported|Not supported|**Supported**|
 
 To know more about the Shell package versioning take a look at the diagram [here](./rancher-2.9-support).
 

docusaurus/docusaurus.config.js

@@ -54,7 +54,7 @@ const config = {
         lastVersion:        'current',
         versions:           {
           current: {
-            label: '3.x.x',
+            label: 'v3',
             path:  'next',
           },
         },
@@ -70,6 +70,20 @@ const config = {
         showLastUpdateTime: true
       },
     ],
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        createRedirects(existingPath) {
+          if (existingPath.includes('/extensions') && !existingPath.includes('/next') && !existingPath.includes('/v2')) {
+            return [
+              existingPath.replace('/extensions', '/extensions/next')
+            ];
+          }
+
+          return undefined; // Return a falsy value: no redirect created
+        },
+      },
+    ],
   ],
 
   themeConfig:

docusaurus/extensionSidebar.js

@@ -69,6 +69,7 @@ const sidebars = {
           label: 'Advanced',
           items: [
             'advanced/air-gapped-environments',
+            // 'advanced/fix-annotations-published-extensions',
             'advanced/provisioning',
             'advanced/localization',
             'advanced/hooks',

docusaurus/extensions_versioned_docs/version-v2/changelog.md

@@ -0,0 +1,18 @@
+# Changelog
+
+> **Rancher 2.10.0** will introduce the migration to Vue 3 - extensions will need to be updated to Vue 3 - read more [**here**](./rancher-2.10-support.md)  
+  
+> **Rancher 2.9.0** contains changes that may require updates to extensions - read more [**here**](./rancher-2.9-support.md)  
+  
+
+
+| Date | Version | Description |
+|---|---|---|
+| 09 July 2024 | 1.2.3 | Minor bug fixes |
+| 09 July 2024 | [**2.0.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.1) | Minor bug fixes |
+| 01 July 2024 | 1.2.2 | First release of a new `Shell` version, but codewise similar to `0.5.3` in order to keep extensions api versioning up to par with shell versioning |
+| 01 July 2024 | [**2.0.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v2.0.0) | Various fixes to the `Shell` package in order to make it compliant with Rancher 2.9 |
+| 15 February 2024 | [**0.5.3**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.3) | Inclusion of the replacement of `Vue.extend` to `defineComponent` with proper fix |
+| 31 January 2024 | [**0.5.2**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.2) | Fix `parse tag name` check in workflows for publishing extensions |
+| 29 January 2024 | [**0.5.1**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.1) | Revert changes to replacement of `Vue.extend` to `defineComponent` because of impact on extensions |
+| 24 January 2024 | [**0.5.0**](https://github.com/rancher/dashboard/releases/tag/shell-pkg-v0.5.0) | Add support for Gitlab workflows for publishing extensions |

docusaurus/extensions_versions.json

@@ -1,3 +1,3 @@
 [
-  "2.0.x"
+  "v2"
 ]