Simplify Upgrade Guide structure

Closes #27632

Signed-off-by: AndyMunro <amunro@redhat.com>
Signed-off-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>

docs/documentation/topics/templates/document-attributes.adoc

@@ -7,6 +7,9 @@
 :project_versionNpm: 999.0.0-SNAPSHOT
 :project_versionDoc: DEV
 
+:archivebasename: keycloak
+:archivedownloadurl: https://github.com/keycloak/keycloak/releases/download/{project_version}/keycloak-{project_version}.zip
+
 :standalone:
 :api-management!:
 :on-prem:

docs/documentation/upgrading/topics.adoc

@@ -1,3 +1,3 @@
-include::topics/keycloak/intro.adoc[leveloffset=0]
+include::topics/intro.adoc[leveloffset=0]
-include::topics/keycloak/upgrading.adoc[leveloffset=0]
+include::topics/changes/changes.adoc[leveloffset=0]
-include::topics/keycloak/changes.adoc[leveloffset=0]
+include::topics/upgrading.adoc[leveloffset=0]

docs/documentation/upgrading/topics/changes/changes-23_0_0.adoc

@@ -180,6 +180,7 @@ some user profile classes and some validator related classes (but not builtin va
 `keycloak-server-spi` module. However, the packages for java classes remain the same. You might be affected in some corner cases, such as when you
 are overriding the built-in implementation with your own `UserProfileProvider` implementation However, note that `UserProfileProvider` is an unsupported SPI.
 
+ifeval::[{project_community}==true]
 = Removal of the Map Store
 
 The Map Store has been an experimental feature in previous releases.
@@ -187,6 +188,7 @@ Starting with this release, it is removed and users should continue to use the c
 
 Since this release, it is no longer possible to use `--storage` related CLI options.
 The modules `keycloak-model-map*` have been removed.
+endif::[]
 
 = Removed namespaces from our translations
 We moved all translations into one file for the admin-ui, if you have made your own translations or extended the admin ui you will need to migrate them to this new format.

docs/documentation/upgrading/topics/download.adoc

@@ -0,0 +1,14 @@
+[[_install_new_version]]
+
+== Downloading the {project_name} server
+
+Once you have prepared for the upgrade, you can download the server.
+
+.Procedure
+
+. Download and extract {archivedownloadurl}[{archivebasename}-{project_version}.zip]
+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.

docs/documentation/upgrading/topics/install_new_version.adoc

@@ -1,14 +0,0 @@
-[[_install_new_version]]
-
-== Upgrading the {project_name} server
-
-It is important that you upgrade {project_name} server before upgrading the adapters.
-
-.Prerequisites
-* Handle any open transactions and delete the data/tx-object-store/ transaction directory.
-
-.Procedure
-. Download the new server archive
-. Move the downloaded archive to the desired location.
-. Extract the archive. This step installs a clean instance of the latest {project_name} release.
-. Copy `conf/`, `providers/` and `themes/` from the previous installation to the new installation.

docs/documentation/upgrading/topics/intro.adoc

@@ -0,0 +1,11 @@
+[[intro]]
+
+== Upgrading {project_name}
+
+This guide describes how to upgrade {project_name}. Use the following procedures in this order:
+
+. Review the migration changes from the previous version of {project_name}.
+. Upgrade the {project_name} server.
+. Upgrade the {project_name} adapters.
+. Upgrade the {project_name} Admin Client.
+

docs/documentation/upgrading/topics/keycloak/intro.adoc

@@ -1,9 +0,0 @@
-[[intro]]
-
-== Upgrading Keycloak
-
-This guide describes how to upgrade {project_name}. It is recommended that you start by upgrading the {project_name}
-server first and {project_name} adapters second.
-
-Before upgrading make sure to read the instructions carefully and carefully review the changes listed in
-<<migration-changes,Migration Changes>>.

docs/documentation/upgrading/topics/keycloak/upgrading.adoc

@@ -1,15 +0,0 @@
-[[_upgrading]]
-
-== Upgrading the {project_name} server
-
-include::../prep_migration.adoc[leveloffset=1]
-
-include::../install_new_version.adoc[leveloffset=1]
-
-include::../migrate_db.adoc[leveloffset=1]
-
-include::../migrate_themes.adoc[leveloffset=1]
-
-include::../upgrade_adapters.adoc[leveloffset=1]
-
-include::../upgrade_admin_client.adoc[leveloffset=1]

docs/documentation/upgrading/topics/migrate_db.adoc

@@ -1,21 +1,15 @@
 [[_migrate_db]]
 
-== Database migration
+== Migrating the database
 
 {project_name} can automatically migrate the database schema, or you can choose to do it manually. By default the
 database is automatically migrated when you start the new installation for the first time.
 
 === Automatic relational database migration
 
-To perform an automatic migration, start the server connected to the desired database.
+To perform an automatic migration, start the server connected to the desired database.  If the database schema has changed for the new server version, the migration starts automatically unless the database has too many records.
-If the database schema has changed for the new version of the server, it will be migrated.
 
-Creating an index on huge tables with millions of records can easily take a huge amount of time
+For example, creating an index on tables with millions of records can be time-consuming and cause a major service disruption.  Therefore, a threshold of `300000` records exists for automatic migration.  If the number of records exceeds this threshold, the index is not created. Instead, you find a warning in the server logs with the SQL commands that you can apply manually.
-and potentially cause major service disruption on upgrades.
-For those cases, we added a threshold (the number of records) for automated index creation.
-By default, this threshold is `300000` records.
-When the number of records is higher than the threshold, the index is not created automatically,
-and there will be a warning message in server logs including SQL commands which can be applied later manually.
 
 To change the threshold, set the `index-creation-threshold` property, value for the default `connections-liquibase` provider:
 
@@ -34,7 +28,7 @@ default `connections-jpa` provider:
 kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual
 ----
 
-When you start the server with this configuration it checks if the database needs to be migrated.
+When you start the server with this configuration, the server checks if the database needs to be migrated.
 The required changes are written to the `bin/keycloak-database-update.sql` SQL file that you can review and manually run against the database.
 
 To change the path and name of the exported SQL file, set the `migration-export` property for the
@@ -45,6 +39,6 @@ default `connections-jpa` provider:
 kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>
 ----
 
-For further details on how to apply this file to the database, see the documentation for the relational database you're using.
+For further details on how to apply this file to the database, see the documentation for your relational database.
 After the changes have been written to the file, the server exits.
 

docs/documentation/upgrading/topics/migrate_themes.adoc

@@ -1,80 +1,58 @@
 [[_migrate_themes]]
 
-== Theme migration
+== Migrating themes
 
-If you have created any custom themes they must be migrated to the new server. Any changes to the built-in themes might
+If you created custom themes, those themes must be migrated to the new server. Also, any changes to the built-in themes might need to be reflected in your custom themes, depending on which aspects you customized.
-need to be reflected in your custom themes, depending on which aspects you have customized.
 
-You must copy your custom themes from the old server `themes` directory to the new server `themes` directory.
+.Procedure
-After that you need to review the changes below and consider if the changes need to be applied to your custom theme.
 
-In summary:
+. Copy your custom themes from the old server `themes` directory to the new server `themes` directory.
-
+. Use the following sections to migrate templates, messages, and styles.
-* If you have customized any of the changed templates listed below you need to compare the template from the base theme
+* If you customized any of the updated templates listed in <<migration-changes,Migration Changes>>, compare the template from the base theme to check for any changes you need to apply.
-  to see if there are changes you need to apply.
+* If you customized messages, you might need to change the key or value or to add additional messages.
-* If you have customized any of the styles and are extending the {project_name} themes you need to review the changes to
+* If you customized any styles and you are extending the {project_name} themes, review the changes to the styles. If you are extending the base theme, you can skip this step.
-  the styles. If you are extending the base theme you can skip this step.
-* If you have customized messages you might need to change the key or value or to add additional messages.
-
-ifeval::[{project_product}==true]
-Each step is described in more detail below the list of changes.
-
-include::rhsso/migrate_themes-changes-73.adoc[leveloffset=0]
-include::rhsso/migrate_themes-changes-72.adoc[leveloffset=0]
-include::rhsso/migrate_themes-changes-71.adoc[leveloffset=0]
-endif::[]
 
 === Migrating templates
 
-If you have customized any of the templates you need to carefully review the changes that have been made to the templates
+If you customized any template, review the new version to decide about updating your customized template. If you made minor changes, you could compare the updated template to your customized template. However, if you made many changes, consider comparing the new template to your customized template. This comparison will show you what changes you need to make.
-to decide if you need to apply these changes to your customized templates. Most likely you will need to apply the same
-changes to your customized templates. If you have not customized any of the listed templates you can skip this section.
 
-A best practice is to use a diff tool to compare the templates to see what changes you might need to make to your
+You can use a diff tool to compare the templates. The following screenshot compares the `info.ftl` template from the Login theme and an example custom theme:
-customized template. If you have only made minor changes it is simpler to compare the updated template to your
-customized template. However, if you have made many changes it might be easier to compare the new template to your
-customized old template, as this will show you what changes you need to make.
 
-The following screenshot compares the info.ftl template from the Login theme and an example custom theme:
+.Updated version of a Login theme template versus a custom Login theme template
+image:images/theme-migration-meld-info-1.png[Updated version of a Login theme template versus a custom Login theme template]
 
-.Comparison of the updated version of a Login theme template with an example custom Login theme template
+This comparison shows that the first change (`Hello world!!`) is a customization, while the
-image:images/theme-migration-meld-info-1.png[]
-
-From this comparison it is easy to identify that the first change (`Hello world!!`) was a customization, while the
 second change (`if pageRedirectUri`) is a change to the base theme. By copying the second change to your custom template,
 you have successfully updated your customized template.
 
-For the alternative approach the following screenshot compares the info.ftl template from the old installation with
+In an alternative approach, the following screenshot compares the `info.ftl` template from the old installation with
-the updated info.ftl template from the new installation:
+the updated `info.ftl` template from the new installation:
 
-.Comparison of the Login theme template from the old installation with the updated version of the Login theme template
+.Login theme template from the old installation versus the updated Login theme template
-image:images/theme-migration-meld-info-2.png[]
+image:images/theme-migration-meld-info-2.png[Login theme template from the old installation versus the updated Login theme template]
 
-From this comparison it is easy to identify what has been changed in the base template. You will then manually have to
+This comparison shows what has been changed in the base template. You can then manually make the same changes to your modified template. Since this approach is more complex, use
-make the same changes to your modified template. Since this approach is not as simple as the first approach, only use
+this approach only if the first approach is not feasible.
-this approach if the first one is not feasible.
 
 === Migrating messages
 
-If you have added support for another language, you need to apply all the changes listed above. If you have not added
+If you added support for another language, you need to apply all the changes listed above. If you have not added
-support for another language, you might not need to change anything; you only have to make changes if you have changed
+support for another language, you might not need to change anything. You need to make changes only if you have changed
 an affected message in your theme.
 
-For added values, review the value of the message in the base theme to determine if you need to customize that message.
+.Procedure
 
-For renamed keys, rename the key in your custom theme.
+. For added values, review the value of the message in the base theme to determine if you need to customize that message.
 
-For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.
+. For renamed keys, rename the key in your custom theme.
+
+. For changed values, check the value in the base theme to determine if you need to make changes to your custom theme.
 
 === Migrating styles
 
-If you are inheriting styles from the keycloak or rh-sso themes you might need to update your custom styles to reflect
+You might need to update your custom styles to reflect changes made to the styles from the built-in themes. Consider using a diff tool to compare the changes to stylesheets between the old server installation and the new server installation.
-changes made to the styles from the built-in themes.
 
-A best practice is to use a diff tool to compare the changes to stylesheets between the old server installation and the
+For example:
-new server installation.
-
-For example, using the diff command:
 
 [source,bash,subs=+attributes]
 ----
@@ -83,4 +61,3 @@ $ diff {project_dirref}_OLD/themes/keycloak/login/resources/css/login.css \
 ----
 
 Review the changes and determine if they affect your custom styling.
-

docs/documentation/upgrading/topics/prep_migration.adoc

@@ -2,20 +2,18 @@
 
 == Preparing for upgrading
 
-Before you upgrade, be aware of the order in which you need to perform the upgrade steps. In particular, be sure to upgrade {project_name} server before you upgrade the adapters.
+Perform the following steps before you upgrade the server.
+
+.Procedure
+. Back up the old installation, such as configuration, themes, and so on.
+. Handle any open transactions and delete the `data/tx-object-store/` transaction directory.
+
+. Back up the database using instructions in the documentation for your relational
+  database.
++
+The database will no longer be compatible with the old server after you upgrade the server. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.
 
 [WARNING]
 ====
-In a minor upgrade of {project_name}, all user sessions are lost. After the upgrade, all users will have to log in again.
+After upgrade of {project_name}, except for offline user sessions, user sessions are lost. Users will have to log in again.
 ====
-
-.Procedure
-. Back up the old installation (configuration, themes, and so on).
-. Back up the database using instructions in the documentation for your relational
-  database.
-. Upgrade the {project_name} server.
-+
-The database will no longer be compatible with the old server after the upgrade.
-. If you need to revert the upgrade, first restore the old installation, and then restore the database from the backup copy.
-. Upgrade the adapters.
-

docs/documentation/upgrading/topics/upgrade_adapters.adoc

@@ -2,58 +2,30 @@
 
 [[_upgrade_adapters]]
 
-It is important that you upgrade {project_name} server first, and then upgrade the adapters. Earlier versions of the
+After you upgrade the {project_name} server, you can upgrade the adapters. Earlier versions of the
-adapter might work with later versions of {project_name} server, but earlier versions of {project_name} server might not
+adapter might work with later versions of the {project_name} server, but earlier versions of the {project_name} server might not
 work with later versions of the adapter.
 
 [[_compatibility_with_older_adapters]]
 == Compatibility with older adapters
 
-As mentioned above, we try to support newer release versions of {project_name} server working with older release versions of the adapters.
+Newer versions of the {project_name} server potentially work with older versions of the adapters.
-However, in some cases we need to include fixes on the {project_name} server side which may break compatibility with older versions
+However, some fixes of the {project_name} server may break compatibility with older versions
-of the adapters. For example, when we implement new aspects of the OpenID Connect specification, which older client adapter versions
+of the adapters. For example, a new implementation of the OpenID Connect specification may not match older client adapter versions.
-were not aware of.
 
-In those cases, we added Compatibility modes. For OpenId Connect clients, there is a section named `OpenID Connect Compatibility Modes`
+For this situation, you can use Compatibility modes. For OpenID Connect clients, the Admin Console includes *OpenID Connect Compatibility Modes* on the page with client details. With this option, you can disable some new aspects of the {project_name} server
-in the {project_name} admin console, on the page with client details. Here, you can disable some new aspects of the {project_name} server
+to preserve compatibility with older client adapters. For more details, see the tool tips of individual switches.
-to preserve compatibility with older client adapters. More details are available in the tool tips of individual switches.
 
 [[_upgrade_eap_adapter]]
 == Upgrading the EAP adapter
 
-ifeval::[{project_product}==true]
-
-.Procedure
-If you originally installed the adapter using a downloaded archive, to upgrade the {appserver_name} adapter, perform the following procedure.
-
-. Download the new adapter archive.
-. Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory.
-. Unzip the downloaded archive into `{appserver_dirref}`.
-
-.Procedure
-If you originally installed the adapter using RPM, to upgrade the adapter, complete the following steps, which are different depending on whether you are performing a minor or a micro upgrade:
-
-. For minor upgrades, use Yum to uninstall any adapters you currently have installed and then use Yum to install the new version of the adapters.
-. For micro upgrades, use Yum to upgrade the adapter. This is the only step for micro upgrades.
-+
-[source,bash,options="nowrap"]
-----
-yum update
-----
-
-endif::[]
-
-ifeval::[{project_community}==true]
-
-.Procedure
 To upgrade the {appserver_name} adapter, complete the following steps:
 
+.Procedure
 . Download the new adapter archive.
 . Remove the previous adapter modules by deleting the `{appserver_dirref}/modules/system/add-ons/keycloak/` directory.
 . Unzip the downloaded archive into `{appserver_dirref}`.
 
-endif::[]
-
 [[_upgrade_js_adapter]]
 == Upgrading the JavaScript adapter
 
@@ -62,15 +34,15 @@ To upgrade a JavaScript adapter that has been copied to your web application, pe
 .Procedure
 
 . Download the new adapter archive.
-. Overwrite the keycloak.js file in your application with the keycloak.js file from the downloaded archive.
+. Overwrite the `keycloak.js` file in your application with the `keycloak.js` file from the downloaded archive.
 
 [[_upgrade_nodejs_adapter]]
-== Upgrading the Node.js adapter
+== Upgrading the `Node.js` adapter
 
-To upgrade a Node.js adapter that has been copied to your web application, perform the following procedure.
+To upgrade a `Node.js` adapter that has been copied to your web application, perform the following procedure.
 
 .Procedure
 . Download the new adapter archive.
-. Remove the existing Node.js adapter directory
+. Remove the existing `Node.js` adapter directory
 . Unzip the updated file into its place
-. Change the dependency for keycloak-connect in the package.json of your application
+. Change the dependency for keycloak-connect in the `package.json` of your application

docs/documentation/upgrading/topics/upgrade_admin_client.adoc

@@ -2,7 +2,7 @@
 
 [[_upgrade_admin_client]]
 
-It is important that you upgrade the {project_name} server first, and then upgrade the admin-client. Earlier versions of the
+Be sure that you upgrade the {project_name} server before you upgrade the admin-client. Earlier versions of the
 admin-client might work with later versions of {project_name} server, but earlier versions of {project_name} server might not
-work with later versions of the admin-client. It is recommended to use the admin-client version that matches the used 
+work with later versions of the admin-client. Therefore, use the admin-client version that matches the current 
 {project_name} server version.

docs/documentation/upgrading/topics/upgrading.adoc

@@ -0,0 +1,17 @@
+[[_upgrading]]
+
+== Upgrading the {project_name} server
+
+You upgrade the server before you upgrade the adapters.
+
+include::prep_migration.adoc[leveloffset=1]
+
+include::download.adoc[leveloffset=1]
+
+include::migrate_db.adoc[leveloffset=1]
+
+include::migrate_themes.adoc[leveloffset=1]
+
+include::upgrade_adapters.adoc[leveloffset=1]
+
+include::upgrade_admin_client.adoc[leveloffset=1]