Release Notes for XWiki 12.0-rc-1

Version 10.1 by Guillaume Delhumeau on 2020/01/23
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

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.

<insert description of release here>

New and Noteworthy (since XWiki <version - 1>)

Full list of issues fixed and Dashboard for <full version here even for RC, e.g. 10.5>.

For Users

  • Emoji Support Enabled in WYSIWYG Editor: You can now insert emoji from the WYSIWYG editor using the dedicated toolbar button. This is done using the Emoji CKEditor Plugin. See the CKEditor Integration for more information.

  • Rendered Changes Using Image Data: A change in the source URL, or reference, of an image displayed on a wiki page, where the image itself is not modified, doesn't appear in the rendered diff anymore when comparing the revisions of that page.

For Admins

Name Strategies for Wiki Pages

A new Name Strategy Module has been introduced to allow administrators to have more control on the wiki page names.
The name strategies allow to validate and transform page names before they are created to comply with a defined policy.
The transformation of page name is performed before page creations through XWiki UI, while page name validation is performed at the API level.

Two strategies have been implemented as a start for this new feature:
  - the Character Replacement Strategy: allows to define forbidden characters in page names, and replacement characters for each. If no replacement characters are defined, the forbidden characters are simply removed from page names.
  - the Slug Name Strategy: allows to normalize page names to remove any special characters and accents.

By default, the Character Replacement Strategy is used with "/" (slash) and "\" (backslash) as forbidden characters, without defined characters. Only the page name transformation is enabled, page name validation is still experimental and should be used with caution. 

This new feature can be setup in the Administration in Editing > Name Strategies.


  • XAR export improvement: A new version of the XAR format has been introduced to improve the way attachment history is exported:

    • it's streamable (exporting an attachment history used to require a lot of memory)
    • version with identical content are de-duplicated (for example the history contain the current version so with the old format it's stored in both the current version and the history)

    This new format is used by default to store deleted documents but not yet in the XAR export administration, should be enabled in 12.0 final.

  • Disable deprecation warnings: A new property property logging.deprecated.enabled allow controlling if warning related to use of deprecated APIs should be logged or not. See Logging Module for more details.

  • Solr Debian package: A new xwiki-solr-core Debian package is now provided, which automatically registers an xwiki core in a standalone Solr instance (provided it uses the standard setup).

  • Select the Wiki Home Page with the new Page Picker: The wiki descriptor administration section is now using the new page picker for the home page field.

For Developers

Velocity upgrade to 2.2

After 9 years Velocity finally got a update. You can see a detailed changelog on but here are the important new things from XWiki script authors:

  • Allow expressions inside []: $foo[$bar + 1]
  • New strategy for reference boolean evaluation:
    • return false for a null object
    • return its value for a Boolean object, or the result of the getAsBoolean() method if it exists.
    • if directive.if.emptycheck is false (true by default), stop here and return true.
    • check for emptiness:
      • return whether an array is empty.
      • return whether isEmpty() is false (covers String and all Collection classes).
      • return whether length() is zero (covers CharSequence classes other than String).
      • returns whether size() is zero.
      • return whether a Number strictly equals zero.
    • check for emptiness after explicit conversion methods:
      • return whether the result of getAsString() is empty (and false for a null result) if it exists.
      • return whether the result of getAsNumber() strictly equals zero (and false for a null result) if it exists.
  • Support $array.empty, as for $list.empty
  • Fix parsing of $obj._method()
  • Have #foreach honnor the Closeable interface on the iterator
  • Fix regression: #set<tab>left-paren no longer valid grammar
  • Fix parser for '$map{key}' text rendering
  • #foreach should work over any Iterable class
  • Method arguments can now be expressions
  • Fixed quotes escaping so that doubling single quotes only works when enclosing quotes are single quotes (and same behaviour for double quotes)
  • Add ability to specify default values for macro parameters, e.g.; #macro(foo bar=1)
  • Add ability to place line comments next to macro parameter definitions
  • Block directives no longer require parenthesis so #@foo #end is now allowed. Also, brackets now work with Block Macros so #{@foo}bar#end works
  • Default block for empty loops: #foreach($i in []) loop block #else empty #end
  • Rendering of arrays should display their content, as for lists
  • New generic $collectiontool which replaces and enhances the former SortTool
  • New generic $logtool

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.0RC1

Velocity 2.2 upgrade

While Velocity upgrade bring a lot of nice new improvements it also comes with unavoidable behavior changes that might be a breackage for your scripts or break some extensions:

  • The Velocity Java API changed quite a lot, if you use advanced features directly in Java there is a big chance that you need to update your code. You can find more details on
  • Most names of Velocity configuration properties have changed ; old names are still functional but will emit a deprecation warning in the log. See the Configuration Changes in Velocity 2.1 page.
  • We tried to reduce as much as possible the breaking changes in the language using some retro compatibility flags provided by Velocity and some hacks on XWiki side but there is still things for which you might want to be carefull:
    • Deprecations: A lot of APIs are now deprecated, they should work fine but will produce a warning in the log (unless you disabled that using the new property logging.deprecated.enabled in
      • $listtool was already deprecatedd since Velocity 1.6 which added support for allows all List methods to be called on arrays
      • $sorttool replaced by $collectiontool
      • $velocityCount and $velocityHasNext where already deprecated in Velocity 1.7 without producing any deprecation warning, they now do
    • Breackages:
      • No more Velocity macro semi-local context: in Velocity 1.7 variable set inside a macro were set both in the global context and in a special macro local context. In Velocity 2.x this local context does not exist anymore. In pratice in means that if, in your macro, you #set a variable and execute another Velocity template which set the same variable your macro will be affected while it used to be "protected" by the previous explicit #set. It's now (since Velocity 1.7 actually) recommended to use the $macro map to manipulate local variable (as in #set($macro.myLocalVar = "value")).
    • Known bugs:

API Breakages

The following APIs were modified since XWiki 11.10.2:

Failed to execute the [groovy] macro. Cause: [Error number 9001 in 9: Access denied in edit mode on document xwiki:ReleaseNotes.Data.XWiki.12\.0RC1.WebHome]. Click on this message for details.


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

  • Adel Atallah
  • Anca Luca
  • Björn Ludwig
  • Carlos Amengual
  • Christian Fröhlich
  • Clément Aubin
  • DenisF
  • flyger
  • Guillaume Delhumeau
  • Marius Dumitru Florea
  • Prachi Joshi
  • Roman Ivanov
  • Simon Urli
  • Thomas Mortagne
  • tomaszkowalczyk94
  • Vincent Massol
  • xrichard

Get Connected