From 2b2d7bbcbe487bd707619c1ea697c65850cd1dce Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Tue, 3 Jun 2025 16:14:11 +0200 Subject: [PATCH] Updated documentation to handle the conf folder on upgrades (#40175) Closes #40046 Signed-off-by: Alexander Schwartz --- .../upgrading/topics/changes/changes-26_3_0.adoc | 8 ++++++++ docs/documentation/upgrading/topics/download.adoc | 6 +++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc index 1fc4c2d8c11..a92c1285628 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_3_0.adoc @@ -132,3 +132,11 @@ a new parameter `subGroupsCount` was introduced to the following endpoints: With this parameter, clients can decide whether the count should be returned to each individual group returned. To not break existing deployments, this parameter defaults to `true` so that the count is returned if the parameter is not set. + +=== Upgrade procedure changed for the distribution + +If you are upgrading {project_name} by downloading the distribution, the upgrade procedure has been changed. Previously it recommended copying over the contents from the `conf/` folder from the old to the new installation. +The new procedure recommends to re-apply any changes to `cache-ispn.xml` or a custom cache configuration based on the file included in the new version. + +This prevents accidentally downgrading functionality, for example, by using an old `cache-ispn.xml` file from a previous version. + diff --git a/docs/documentation/upgrading/topics/download.adoc b/docs/documentation/upgrading/topics/download.adoc index 0910855f229..80ec3b1dfcd 100644 --- a/docs/documentation/upgrading/topics/download.adoc +++ b/docs/documentation/upgrading/topics/download.adoc @@ -11,4 +11,8 @@ from the {project_name} website. + After extracting this file, you should have a directory that is named `{archivebasename}-{project_version}`. . Move this directory to the desired location. -. Copy `conf/`, `providers/` and `themes/` from the previous installation to the new installation. \ No newline at end of file +. Copy `providers/` and `themes/` from the previous installation to the new installation. +. Copy all files except `cache-ispn.xml` from `conf/` from the previous installation to the new installation. +. If you modified `cache-ispn.xml` or created a custom cache configuration file: +.. Re-apply your changes based on the `cache-ispn.xml` file shipped with the new installation, and place them in the new installation. +.. Review the latest {project_name} configuration options for cache sizes and transport stacks if they can be used instead of your modifications as they provide better documentation, additional validations and functionality, and a simpler upgrade experience.