From f1ec0a9bb692b5fd9c289833c5908d93512f8979 Mon Sep 17 00:00:00 2001 From: mposolda Date: Mon, 16 Sep 2024 16:58:50 +0200 Subject: [PATCH] Release notes and upgrading guide for the client libraries closes #30815 Signed-off-by: mposolda Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> Signed-off-by: Marek Posolda --- .../release_notes/topics/26_0_0.adoc | 21 +++++++++++++++++++ .../topics/changes/changes-26_0_0.adoc | 14 +++++++++++++ .../topics/upgrade_admin_client.adoc | 8 ------- .../upgrading/topics/upgrade_client_libs.adoc | 21 +++++++++++++++++++ .../upgrading/topics/upgrading.adoc | 2 +- 5 files changed, 57 insertions(+), 9 deletions(-) delete mode 100644 docs/documentation/upgrading/topics/upgrade_admin_client.adoc create mode 100644 docs/documentation/upgrading/topics/upgrade_client_libs.adoc diff --git a/docs/documentation/release_notes/topics/26_0_0.adoc b/docs/documentation/release_notes/topics/26_0_0.adoc index 5f1ba70f36..be483675a3 100644 --- a/docs/documentation/release_notes/topics/26_0_0.adoc +++ b/docs/documentation/release_notes/topics/26_0_0.adoc @@ -178,6 +178,27 @@ It is possible to revert this behavior to the previous state by disabling the fe For information on how to upgrade, see the link:{upgradingguide_link}[{upgradingguide_name}]. += Client libraries updates + +== Dedicated release cycle for the client libraries + +From this release, some of the {project_name} client libraries will have release cycle independent of the {project_name} server release cycle. The 26.0.0 release may be the last one +when the client libraries are released together with the {project_name} server. But from now on, the client libraries may be released at a different time than the {project_name} server. + +The client libraries are these artifacts: + +* Java admin client - Maven artifact `org.keycloak:keycloak-admin-client` +* Java authorization client - Maven artifact `org.keycloak:keycloak-authz-client` +* Java policy enforcer - Maven artifact `org.keycloak:keycloak-policy-enforcer` + +It is possible that in the future, some more libraries will be included. + +== Compatibility of the client libraries with the server + +Beginning with this release, we are testing and supporting client libraries with the same server version and a few previous major server versions. + +For details about supported versions of client libraries with server versions, see the link:{upgradingguide_link}#_upgrade_client_libraries[{upgradingguide_name}]. + = New generalized event types for credentials There are now generalized events for updating (`UPDATE_CREDENTIAL`) and removing (`REMOVE_CREDENTIAL`) a credential. The credential type is described in the `credential_type` attribute of the events. The new event types are supported by the Email Event Listener. diff --git a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc index 46cf684a3a..d8b6de9ba7 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc @@ -270,6 +270,20 @@ The `--optimized` startup option now requires the optimized server image to be b either by running `kc.sh|bat build` first or by any other server commands (like `start`, `export`, `import`) without the `--optimized` flag. += Adapter and misc BOM files are removed + +The `org.keycloak.bom:keycloak-adapter-bom` and `org.keycloak.bom:keycloak-misc-bom` BOM files are removed. The adapter BOM was no longer useful because most of the Java adapters +are removed. The misc BOM had contained only one artifact, `keycloak-test-helper`, and that artifact is also removed in this release. + += keycloak-test-helper is removed + +The maven artifact `org.keycloak:keycloak-test-helper` is removed in this release. The artifact provided a few helper methods for dealing with a Java admin client. If you use the +helper methods, it is possible to fork them into your application if needed. + += JEE admin-client is removed + +The JEE admin-client is removed in this release. We still keep supporting Jakarta admin-client. + = New generalized event types for credentials There are now generalized events for updating (`UPDATE_CREDENTIAL`) and removing (`REMOVE_CREDENTIAL`) a credential. The credential type is described in the `credential_type` attribute of the events. diff --git a/docs/documentation/upgrading/topics/upgrade_admin_client.adoc b/docs/documentation/upgrading/topics/upgrade_admin_client.adoc deleted file mode 100644 index 86dd22aceb..0000000000 --- a/docs/documentation/upgrading/topics/upgrade_admin_client.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= Upgrading the {project_name} Admin Client - -[[_upgrade_admin_client]] - -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. Therefore, use the admin-client version that matches the current -{project_name} server version. diff --git a/docs/documentation/upgrading/topics/upgrade_client_libs.adoc b/docs/documentation/upgrading/topics/upgrade_client_libs.adoc new file mode 100644 index 0000000000..f33b40df26 --- /dev/null +++ b/docs/documentation/upgrading/topics/upgrade_client_libs.adoc @@ -0,0 +1,21 @@ += Upgrading the {project_name} Client Libraries + +[[_upgrade_client_libraries]] + +The client libraries are those artifacts: + +* Java admin client - Maven artifact `org.keycloak:keycloak-admin-client` +* Java authorization client - Maven artifact `org.keycloak:keycloak-authz-client` +* Java policy enforcer - Maven artifact `org.keycloak:keycloak-policy-enforcer` + +ifeval::[{project_community}==true] +The client libraries are supported with the last supported {project_name} server version. +endif::[] +ifeval::[{project_product}==true] +The client libraries are supported with all the supported {project_name} server versions. The fact that client libraries are supported with more server versions makes the update easier, +so you may not need to update the server at the same time when you update client libraries of your application. +endif::[] + +It is possible that client libraries may work even with the older releases of the {project_name} server, but it is not guaranteed and officially supported. + +It may be needed to consult the javadoc of the client libraries like Java admin-client to see what endpoints and parameters are supported with which {project_name} server version. diff --git a/docs/documentation/upgrading/topics/upgrading.adoc b/docs/documentation/upgrading/topics/upgrading.adoc index 324b980bbc..840fbd337c 100644 --- a/docs/documentation/upgrading/topics/upgrading.adoc +++ b/docs/documentation/upgrading/topics/upgrading.adoc @@ -14,4 +14,4 @@ include::migrate_themes.adoc[leveloffset=1] include::upgrade_adapters.adoc[leveloffset=1] -include::upgrade_admin_client.adoc[leveloffset=1] +include::upgrade_client_libs.adoc[leveloffset=1]