From 8d33701a9ac1d8235d354f9d3d002867d8593089 Mon Sep 17 00:00:00 2001
From: sronveaux <s.ronveaux@biodiversity.be>
Date: Tue, 7 Jan 2025 16:35:55 +0100
Subject: [PATCH] Added upgrade notes from Wegue v2 to v3 for Vue3 and Vuetify3

---
 upgrade-notes.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/upgrade-notes.md b/upgrade-notes.md
index 129adac7..86357f00 100644
--- a/upgrade-notes.md
+++ b/upgrade-notes.md
@@ -1,5 +1,91 @@
 # Upgrade Notes
 
+## v2 -> v3
+
+`Wegue` v3.x transited from `Vue 2` to `Vue 3` and from `Vuetify 2` to `Vuetify 3` which implies a lot of changes.
+
+`Wegue` team tried to introduce as few changes as possible to make the transition as smooth as it can be.  
+This means components are still written using the `Options API` for example.
+
+To be compatible with all the required dependencies, minimal `node` version was raised to `v18.19.0` while minimal `npm` version was also raised to `v10.2.3`.
+
+Changes that were applied on the files present in the [app-starter](https://github.com/wegue-oss/wegue/commits/master/app-starter) directory should also be applied to your custom files present in the `app` directory.  
+Don't forget to apply the changes made to the `.browserlistrc`, `.eslintrc.js` and `vue.config.js` files in the root directory too!
+
+### Vue
+
+`Vue` was upgraded from v2.x to v3.x which implies a lot of breaking changes. Please refer to the official [Vue 3 Migration Guide](https://v3-migration.vuejs.org/), especially its [Breaking Changes part](https://v3-migration.vuejs.org/breaking-changes/) when you upgrade your `Wegue` app.
+
+Comparing changes applied on the components present in the [app-starter](https://github.com/wegue-oss/wegue/commits/master/app-starter) directory should give you a good overview of what has to be done.
+
+Here is a list of the essentials which had to be adapted in the `Wegue` code regarding to the upgrade of `Vue` to version 3.x:
+
+- `<template v-for>` `key` attribute should be placed on the `<template>` tag now rather than on its children.
+- `Vue` now has a concept of *app instance* which completely changes how global configuration can be approached. Some variables that were stored on the `Vue` prototype are now reachable from the *app instance* through `this` inside components.  
+For example, the `application configuration` which was available through `Vue.prototype.$appConfig` can now be accessed using `this.$appConfig`.  
+The same applies to `$appLanguage` and `$isEmbedded`.  
+There is a limitation though as accessing the *app instance* is only possible inside components, not from plain `JavaScript` files.
+- For the same reason, `ViewAnimationUtil` helper functions are now embedded inside a class with the known limitation that it can only be used inside of components.  
+Some changes must be done if you were using those functions directly inside your application.  
+  Something previously written like this:  
+  > `ViewAnimationUtil.to(this.map.getView(), foundFeature.getGeometry());`
+
+  Should be replaced by:
+  > const viewAnimationUtil = new ViewAnimationUtil(this.$appConfig);  
+  viewAnimationUtil.to(this.map.getView(), foundFeature.getGeometry());
+- `Vue` instances can no longer be used to create an *event bus*. `WguEventBus` was rewritten to make use of `tiny-emitter` because of that. This should be fully transparent, however, some edge cases could be encountered if very specific usage is made of it.
+- `ColorTheme mixin` and `Mapable mixin` were rewritten as `composables`. What should be done to migrate those `mixins` to their `composable` counterparts is easier to see by example. Please take a look at the [ThemeSwitcher component](https://github.com/wegue-oss/wegue/blob/master/src/components/themeswitcher/ThemeSwitcher.vue) and the [BackgroundLayerSwitcher component](https://github.com/wegue-oss/wegue/blob/master/src/components/bglayerswitcher/BgLayerSwitcher.vue) respectively.  
+For basic usage, migrating from the `ColorTheme mixin` should be limited to removing the `mixin` registration and adding the following two lines inside the `setup lifecycle hook`:
+    > const { isDarkTheme, isPrimaryDark } = useColorTheme();  
+    > return { isDarkTheme, isPrimaryDark };
+
+  For basic usage, migrating from the `Mapable mixin` should be limited to removing the `mixin` registration, removing the layers retrieval inside the `onMapBound` method and adding the following two lines inside the `setup lifecycle hook`:
+    > const { map, layers } = useMap();  
+    > return { map, layers };
+
+  Please also note that `onMapBound` and `onMapUnbound` are not fired anymore. If you'd like to work with them as before, you have to implement your own `watcher` on the `map` for that. You can refer to the [OverviewMapPanel component](https://github.com/wegue-oss/wegue/blob/master/src/components/overviewmap/OverviewMapPanel.vue) to get a full example.
+
+Currently, the `Vue migration build` is used instead of the native `Vue 3` build. Because of this, usage of features that have changed or been deprecated in `Vue 3` will emit runtime warnings. This can be really useful while migrating an application and ensure everything was dealt with properly.
+
+`Vue migration build` compatibility with `Vue 2` can be configured to suit your needs during the migration phase.  
+Global configuration is made inside the [main.js file](https://github.com/wegue-oss/wegue/blob/master/src/main.js).  
+Options which are compiler-specific can be configured inside the [vue.config.js file](https://github.com/wegue-oss/wegue/blob/master/vue.config.js).
+
+To get more information about this build and how to configure it, please refer to the official [Vue 3 Migration Guide](https://v3-migration.vuejs.org/migration-build).
+
+Usage of the `Vue migration build` will be removed for official `Wegue` v3 release.
+
+### Vuetify
+
+`Vuetify` was upgraded from v2.x to v3.x which implies a lot of breaking changes. Please refer to the official [Vuetify 3 Upgrade Guide](https://vuetifyjs.com/en/getting-started/upgrade-guide/#upgrade-guide) when you upgrade your `Wegue` app.
+
+Comparing changes applied on the components present in the [app-starter](https://github.com/wegue-oss/wegue/commits/master/app-starter) directory should give you a good overview of what has to be done. There were so many changes in the APIs though that each component should be addressed separately. This will certainly be the most tedious part of migrating a complete `Wegue` app.
+
+Here is a list of the essentials which had to be adapted in the `Wegue` code regarding to the upgrade of `Vuetify` to version 3.x:
+
+- `Material Icons` now need the `md:` prefix added to their name. For example, `chevron_left` is now called `md:chevron_left`.  
+`MDI` keep their name unchanged. For example, `mdi-menu-left` has still the same name.  
+Please update icon names accordingly inside your **app code** and inside your **configuration files**.
+- `onprimary` and `onsecondary` colors are now called `on-primary` and `on-secondary` respectively. Please update your configuration files accordingly.  
+Take also note that the `accent` and `anchor` colors were removed while some others such as `surface` have been added by default. You can refer to the official [Theme configuration page](https://vuetifyjs.com/en/features/theme/) for more information. Also keep in mind that you can still create custom colors and are not limited to the standard ones.  
+-  Custom icons format has slightly changed, their definition should now begin with `svg:` and they can be referenced using `$myIconName`.  
+For example, an icon which was defined as `export default 'M 23.16738,3.1894921 18.478314,20.810508 H ... L 20.847525,3.1894921 Z'` should now de defined as `export default 'svg:M 23.16738,3.1894921 18.478314,20.810508 H ... L 20.847525,3.1894921 Z'`. If this was defined inside a file called `app/custom-icons/WLetter.js`, it was displayed using `$vuetify.icons.WLetter` as a name. If the file name hasn't changed, it is now displayable using `$WLetter` as a name.  
+Please update your app code and configuration files accordingly.
+
+### ESLint
+
+`ESLint` and its associated plugins were upgraded to the following versions:
+
+- `eslint` => 8.57.x
+- `eslint-plugin-vue` => 9.32.x
+- `eslint-plugin-vuetify` => 2.5.x
+- `eslint-config-standard` => 17.1.x
+- `@vue/eslint-config-standard` => 8.0.x
+
+As some linting rules were added or changed, you should expect to see error and warnings the first time you will build your updated `Wegue` app.  
+The majority of those can be fixed automatically by running the `npm run lint:fix` command.  
+If you want to momentarily bypass some advanced errors to test your upgraded app or want to adapt linting rules to better suit your preferences, you can modify the `.eslintrc.js` file as needed.
+
 ## v1 -> v2
 
 ### Vue-CLI