Release Notes for XWiki 12.9-rc-1

Version 6.3 by Eduard Moraru on 2020/10/20

This is the release notes for XWiki Commons, XWiki Rendering and XWiki Platform. They share the same release notes as they are released together and have the same version.

This release brings improved display of liked pages and users that like a page, usability improvements when changing page syntax, finer configuration options for skipping the recycle bin and a new and improved Ratings API.

New and Noteworthy (since XWiki 12.8)

Full list of issues fixed and Dashboard for 12.9.

For Users

Like information are displayed in a live table

People liking a page are now displayed in a live table.

Liked pages are displayed in a LiveTable

Liked pages are now displayed in a live table in the user profile.

Changing Page Syntax from Wiki Editor

Changing the page syntax from the Wiki Editor has suffered some updates:

  • the style of the syntax conversion confirmation modal has been improved to be consistent with the other modals we use in XWiki
  • the syntax conversion is not saved right away anymore but when you save the Wiki Editor; canceling the Wiki Editor will also cancel any unsaved syntax change
  • XWiki will warn you when the syntax conversion is not supported

Checkout the Page Editing documentation for additional information.

Changing Page Syntax from WYSIWYG Editor

Changing the page syntax from the WYSIWYG Editor has suffered some updates:

  • we don't reload the entire page anymore but only the WYSIWYG editor instance (in order to take into account the new syntax); the WYSIWYG editor has to be reloaded because the page syntax affects core editor configuration that cannot be changed on the fly (see the CKEditor Integration documentation for more information);
  • the WYSIWYG editor is always reloaded when changing the syntax, no matter whether you choose to convert the content or not (for the reason mentioned above)
  • the editing mode (Source vs. WYSIWYG) is preserved on reload
  • if the new syntax doesn't support WYSIWYG editing (e.g. because it doesn't have a renderer) then the WYSIWYG editor will force the Source mode after the reload and disable the WYSIWYG mode, warning the user about the current limitation.

Checkout the Page Editing documentation for additional information.

Changing Page Syntax from View

Changing the page syntax from the Information tab, while viewing the page, has suffered some updates:

  • XWiki will now propose to convert the page content and meta data to the new syntax, if the conversion is supported, but note that the changes will be saved only after saving the syntax
  • if the syntax conversion is not supported then XWiki will warn the user about the limitation
  • the page title and content are reloaded in order to allow the user to preview the effect of the syntax change before saving the new syntax
  • canceling the syntax change will also reload the page title and content

For Admins

Finer configuration of the "can skip the recycle bin" feature

Allowing Advanced user to skip the recycle bin can now be configured on three locations:

  • In the global administration of the current wiki
  • In the global administration of the main wiki
  • In (see the property details below)

If the default value is found on one location, the next one is tried. If no value is found, the recycle bin skipping is not activated.

Details of the configuration on

#-# [Since 12.9RC1]
#-# Indicates whether skipping the recycle bin when deleting pages is allowed for Advanced users.
#-# It is disabled by default.
#-# This setting is only used if the wiki has a recycle bin activated (xwiki.recyclebin=1 in xwiki.cfg).
#-# This setting can be overloaded:
#-# * By the main wiki in the Refactoring.Code.RefactoringConfigurationClass class of the
#-#   Refactoring.Code.RefactoringConfiguration document of the main wiki.
#-# * By sub-wikis in the Refactoring.Code.RefactoringConfigurationClass class of the
#-#   Refactoring.Code.RefactoringConfiguration document of the sub-wikis (itself overloading the main wiki's
#-#   configuration).
#-# The default value is:
# refactoring.isRecycleBinSkippingActivated = false


For Developers

Async Rendering improvements

When the context document is selected in an asynchronous rendering execution it's also added to "used" entities. That means that if that document is modified the cache result will be invalidated automatically. 

Provide a new API for Ratings

The Ratings API has been rewritten in order to support new use-cases, such as performing rates on different kinds of elements (not only pages) but also using different scales for ratings. This works leads to breaking the existing Ratings API: the Rating Application is automatically supported (you just have to update the extension) but if you used directly the Ratings API for some custom extensions you might be interested about this small guide for migrating it.


  • URLTool improvement: A new toURL(String) has been added to the Velocity $urltool to convert a String to an URL object.

Moved Modules

<description deprecated, retired and moved projects>


The following runtime dependencies have been upgraded (they have a different release cycle than XWiki Commons, XWiki Rendering and XWiki Platform):


The following translations have been updated:

Known issues

Backward Compatibility and Migration Notes

General Notes

  • When upgrading make sure you compare and merge the following XWiki configuration files since some parameters may have been modified, removed or added:
    • xwiki.cfg
    • web.xml
    • hibernate.cfg.xml
  • Add in xwiki.cfg so that XWiki will attempt to automatically migrate your current database to any new schema. Make sure you backup your Database before doing anything.

Issues specific to XWiki 12.9RC1

The Ratings API have been rewritten in order to support more usecases, but we voluntarely broke the backward compatibility when doing so. If you are upgrading from XWiki 12.7RC1 or after, or from an XWiki version on which Ratings Application is installed, you might see some logs like that at first restart:

2020-10-16 17:39:53,897 [main] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.platform:xwiki-platform-distribution-flavor-mainwiki/12.8] on namespace [wiki:xwiki] (InvalidExtensionException: Dependency [org.xwiki.platform:xwiki-platform-oldcore-[12.8]] is incompatible with the core extension [org.xwiki.platform:xwiki-platform-oldcore/12.9-SNAPSHOT])
2020-10-16 17:39:53,897 [main] WARN  ltInstalledExtensionRepository - Invalid extension [org.xwiki.platform:xwiki-platform-ratings-api/12.8] (InvalidExtensionException: Extension [org.xwiki.platform:xwiki-platform-ratings-api/12.8] already exists as a core extension)
2020-10-16 17:39:54,486 [main] ERROR .i.DefaultExtensionInitializer - Failed to initialize local extension [org.xwiki.platform:xwiki-platform-like-api/12.8]
java.lang.NoClassDefFoundError: org/xwiki/ratings/internal/SeparatePageRatingsManager
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(
at Method)
at java.lang.ClassLoader.loadClass(
at java.lang.ClassLoader.loadClass(
at org.xwiki.component.annotation.ComponentAnnotationLoader.getComponentsDescriptors(
at org.xwiki.component.annotation.ComponentAnnotationLoader.register(
at org.xwiki.component.annotation.ComponentAnnotationLoader.initialize(
at org.xwiki.extension.jar.internal.handler.JarExtensionHandler.loadComponents(
at org.xwiki.extension.jar.internal.handler.JarExtensionHandler.install(
at org.xwiki.extension.jar.internal.handler.JarExtensionHandler.initialize(
at org.xwiki.extension.handler.internal.DefaultExtensionHandlerManager.initialize(
at org.xwiki.extension.handler.internal.DefaultExtensionInitializer.initializeExtensionInNamespace(
at org.xwiki.extension.handler.internal.DefaultExtensionInitializer.initializeExtensionInNamespace(
at org.xwiki.extension.handler.internal.DefaultExtensionInitializer.initializeExtension(
at org.xwiki.extension.handler.internal.DefaultExtensionInitializer.initialize(
at org.xwiki.extension.handler.internal.DefaultExtensionInitializer.initialize(
at org.xwiki.component.embed.InitializableLifecycleHandler.handle(
at org.xwiki.component.embed.EmbeddableComponentManager.createInstance(
at org.xwiki.component.embed.EmbeddableComponentManager.getComponentInstance(
at org.xwiki.component.embed.EmbeddableComponentManager.getInstance(
at org.xwiki.component.embed.EmbeddableComponentManager.getInstance(
at org.xwiki.container.servlet.XWikiServletContextListener.contextInitialized(
at org.eclipse.jetty.server.handler.ContextHandler.callContextInitialized(
at org.eclipse.jetty.servlet.ServletContextHandler.callContextInitialized(
at org.eclipse.jetty.server.handler.ContextHandler.contextInitialized(
at org.eclipse.jetty.servlet.ServletHandler.initialize(
at org.eclipse.jetty.servlet.ServletContextHandler.startContext(
at org.eclipse.jetty.webapp.WebAppContext.startWebapp(
at org.eclipse.jetty.webapp.WebAppContext.startContext(
at org.eclipse.jetty.server.handler.ContextHandler.doStart(
at org.eclipse.jetty.servlet.ServletContextHandler.doStart(
at org.eclipse.jetty.webapp.WebAppContext.doStart(
at org.eclipse.jetty.util.component.AbstractLifeCycle.start(
at org.eclipse.jetty.deploy.bindings.StandardStarter.processBinding(
at org.eclipse.jetty.deploy.AppLifeCycle.runBindings(
at org.eclipse.jetty.deploy.DeploymentManager.requestAppGoal(
at org.eclipse.jetty.deploy.DeploymentManager.addApp(
at org.eclipse.jetty.deploy.providers.ScanningAppProvider.fileAdded(
at org.eclipse.jetty.deploy.providers.WebAppProvider.fileAdded(
at org.eclipse.jetty.deploy.providers.ScanningAppProvider$1.fileAdded(
at org.eclipse.jetty.util.Scanner.reportAddition(
at org.eclipse.jetty.util.Scanner.reportDifferences(
at org.eclipse.jetty.util.Scanner.scan(
at org.eclipse.jetty.util.Scanner.doStart(
at org.eclipse.jetty.util.component.AbstractLifeCycle.start(
at org.eclipse.jetty.deploy.providers.ScanningAppProvider.doStart(
at org.eclipse.jetty.util.component.AbstractLifeCycle.start(
at org.eclipse.jetty.deploy.DeploymentManager.startAppProvider(
at org.eclipse.jetty.deploy.DeploymentManager.doStart(
at org.eclipse.jetty.util.component.AbstractLifeCycle.start(
at org.eclipse.jetty.util.component.ContainerLifeCycle.start(
at org.eclipse.jetty.server.Server.start(
at org.eclipse.jetty.util.component.ContainerLifeCycle.doStart(
at org.eclipse.jetty.server.handler.AbstractHandler.doStart(
at org.eclipse.jetty.server.Server.doStart(
at org.eclipse.jetty.util.component.AbstractLifeCycle.start(
at org.eclipse.jetty.xml.XmlConfiguration.lambda$main$1(
at Method)
at org.eclipse.jetty.xml.XmlConfiguration.main(
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(
at sun.reflect.DelegatingMethodAccessorImpl.invoke(
at java.lang.reflect.Method.invoke(
at org.eclipse.jetty.start.Main.invokeMain(
at org.eclipse.jetty.start.Main.start(
at org.eclipse.jetty.start.Main.main(
Caused by: java.lang.ClassNotFoundException: org.xwiki.ratings.internal.SeparatePageRatingsManager
at java.lang.ClassLoader.loadClass(
at java.lang.ClassLoader.loadClass(
... 73 common frames omitted

If not nice, those errors are expected: they are showing that our internal Extension Manager found that the Ratings API compatibility was broken. This error will prevent using the Ratings Application or the Like Application until you have completely performed the upgrade. 

During the upgrade, you will be proposed to remove the old Ratings API extension: keep the default value for it (it should be checked) to avoid any inconsistency. 

Also note that at first start, a data migration of Ratings and Likes will be performed, you might see some logs like that:

2020-10-16 17:40:31,319 [XWiki initialization] INFO  .HibernateDataMigrationManager -   R120901000XWIKI17761 - Move old Ratings XObject to the default Solr rating store.
2020-10-16 17:40:31,319 [XWiki initialization] INFO  .HibernateDataMigrationManager - Checking Hibernate mapping and updating schema if needed for wiki [xwiki]
2020-10-16 17:40:31,508 [XWiki initialization] INFO  .HibernateDataMigrationManager - Starting data migration [R120901000XWIKI17761] with version [120901000] on database [xwiki]
2020-10-16 17:40:31,633 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - [5] pages containing ratings xobjects have been found: those objects will be migrated to the new storage system and will be removed. The pages holding those xobjects will remain
2020-10-16 17:40:35,869 [XWiki Solr index thread] INFO  .HibernateDataMigrationManager - Storage schema updates and data migrations are enabled
2020-10-16 17:40:36,415 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - All pages have been handled to migrate their Ratings xobject. Total: [5] pages handled and [5] xobjects migrated.
2020-10-16 17:40:36,415 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - Starting recomputation of average ratings on rated pages for consistency of data.
2020-10-16 17:40:37,088 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - Average ratings have been recomputed on all [4] pages.
2020-10-16 17:40:37,089 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - Starting migration of Likes information to the Ratings Solr Core.
2020-10-16 17:40:37,100 [XWiki initialization] INFO  SolrDocumentMigration120900000 - [2] like information migrated.
2020-10-16 17:40:37,175 [XWiki initialization] INFO  0901000XWIKI17761DataMigration - The migration is now finished.
2020-10-16 17:40:37,178 [XWiki initialization] INFO  .HibernateDataMigrationManager - Data migration [R120901000XWIKI17761] applied successfully, database [xwiki] upgraded to version [120901000] 

Finally if you have a custom extension or custom scripts using the Ratings API, you will be interested about this migration guide.

API Breakages

The following APIs were modified since <project> <version - 1>:


The following people have contributed code and translations to this release (sorted alphabetically):

<code contributors>

Get Connected