#971: Ability to run "migration script" on update

CHANGELOG.asciidoc

@@ -6,6 +6,7 @@ This file documents all notable changes to https://github.com/devonfw/ide[devonf
 
 Release with new features and bugfixes:
 
+* https://github.com/devonfw/ide/issues/971[#971]: Ability to run "migration script" on update
 * https://github.com/devonfw/ide/issues/991[#991]: Integrate openrewrite feature
 * https://github.com/devonfw/ide/issues/1062[#1062]: Migration support for devon4j 2023.01.001
 * https://github.com/devonfw/ide/issues/1052[#1052]: Fix leading spaces on MacOS

documentation/functions.asciidoc

@@ -290,6 +290,7 @@ Attention: for one installation package the function doReplaceExtractedSkipSingl
 Called with the three parameters path of the file or directory to be moved, the target directory and a backup directory.
 The function creates missing directories, makes a backup from the target directory to the backup directory.
 Then the files specified in the first parameter are moved to the target directory.
+Finally, the link:migration.asciidoc[migration script] is run to migrate the ide to the latest version.
 
 === doReplaceExtractedSkipSingleFolder
 The parameters source directory, target directory, backup directory and possibly a list of files and directories via shell file name expansion (globbing) are passed to the doReplaceExtractedSkipSingleFolder function.

documentation/migration.asciidoc

@@ -0,0 +1,30 @@
+:toc:
+toc::[]
+
+= migration
+
+When we publish a new release, our users can install it to existing devonfw-ide installations via `devon ide update scripts`. 
+Sometimes we do some structural changes and to avoid "polluting" our scripts with legacy handling code, there is a `migration` script under `${DEVON_IDE_HOME}/scripts` that is automatically executed by `devon ide update scripts` after the new release has been installed.
+The `migration` script then executes all potential upgrades in `${DEVON_IDE_HOME}/scripts/migrations/«version»` that are greater or equal to the previously installed version in numerical order.
+
+== upgrade scripts
+The `migrations` folder contains a file for each devonfw-ide version that requires an upgrade migration on installation as illustrated by the following example:
+
+.Structure of migrations folder
+[subs=+macros]
+----
+/migrations
+├──/ ...
+├──/ 2023.03.001
+├──/ 2023.03.003
+├──/ 2023.12.001
+├──/ ...
+----
+
+As you can see, the migrations folder contains scripts with specific ide versions.
+If no upgrade is required for a new version there will be no migration script so there can be gaps in their numbers.
+So if the user runs `devon ide update scripts` on ide with version `«version-x»`, the `migration` script will execute each script in migrations folder from the same version to the latest version in numerical order.
+
+ATTENTION: Since this feature is available with version ´2023.02.001´, older ide's are not affected by the migration.
+We try to reach our users with an announcement to upgrade all installations to that version once released.
+In case you missed to follow this guidance, you can still manually call `migration 2023.02.001` in your `${DEVON_IDE_HOME}/scripts/` folder to fix it.

scripts/src/main/resources/scripts/functions

@@ -780,21 +780,26 @@ function doReplaceExtractedFile() {
   local filename="${1/*\//}"
   local target_dir="${DEVON_IDE_HOME}"
   local target="${DEVON_IDE_HOME}/${filename}"
+  local migration="${DEVON_IDE_HOME}/scripts/migration"
   if [ -n "${2}" ]
   then
     target="${2}"
     target_dir="$(dirname "${2}")"
   fi
   if [ "${target}" = "${DEVON_IDE_HOME}/scripts" ] && doIsWindows
   then
-    (sleep 10;doBackup "${target}" "${3}";doRunCommand "mv '${1}' '${target}'") &
+    (sleep 10;doBackup "${target}" "${3}";doRunCommand "mv '${1}' '${target}'";doRunCommand "'${migration}'") &
   else
     doBackup "${target}" "${3}"
     if [ ! -d "${target_dir}" ]
     then
       mkdir -p "${target_dir}"
     fi
     doRunCommand "mv '${1}' '${target}'"
+    if [ "${target}" = "${DEVON_IDE_HOME}/scripts" ]
+    then
+      doRunCommand "'${migration}'"
+    fi
   fi
 }
 

scripts/src/main/resources/scripts/migration

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+# shellcheck source=scripts/functions
+source "$(dirname "${0}")"/functions
+
+from_version=2023.01.001
+devon_version="${DEVON_IDE_HOME}/.devon.software.version"
+
+if [ -f "${devon_version}" ]  
+then
+  from_version="$(cat ${devon_version})"
+fi
+
+MIGRATIONS_DIR="${DEVON_IDE_HOME}/scripts/migrations"
+
+if [ -d "${MIGRATIONS_DIR}" ]
+then
+  cd "${MIGRATIONS_DIR}"
+  for migrate_to_version in  $(ls | sort -n)
+  do
+    doVersionCompare "${from_version}" "${migrate_to_version}"
+    result="${?}"
+    if [ "${result}" -eq 2 ]
+    then
+      doEcho "Run migration to version ${migrate_to_version}"
+      bash "${migrate_to_version}"
+      migration_result="${?}"
+      if [ "${migration_result}" -ne 0 ]
+      then
+        doAskToContinue "The migration to version ${migrate_to_version} failed. Would you like to continue?"
+      else
+        echo "${migrate_to_version}" > "${devon_version}"
+        doEcho "${devon_version} is set to version ${migrate_to_version}"
+      fi
+    fi
+  done
+else
+  doWarning "Migrations directory does not exist in ${MIGRATIONS_DIR}"
+fi