Release Notes for XWiki 12.0

Last modified by Ilie Andriuta on 2020/06/01
Contents

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.

To start this new year, we have updated a lot of our dependencies, to give some freshness to the whole platform. For administrators, it is now possible to define name strategies for new pages. For developers, the new big change is the upgrade of Velocity to the new 2.2 version, which support new syntax expressions. We also improved the performance when exporting pages to XAR by introducing a new format, users are able to chose the right formats depending on the target XWiki version. In addition, more than 40 bugs has been fixed since the release of XWiki 11.10.2.

Some important bugs have been discovered since XWiki 12.0 has been released:

If one or several of these bugs impact you, then you should wait for the next version of XWiki (12.1) that will be released soon!

New and Noteworthy (since XWiki 11.10.2)

Full list of issues fixed and Dashboard for XWiki 12.0.

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.

name-strategy-configuration.png

Export Target XWiki Version

 
The Export administration section has a new option named "Target XWiki version" that is useful if you need to generate a XAR that is compatible with an older version of XWiki. For instance, if you need to import the generated XAR in an XWiki version older than 12.0 then you should set "Target XWiki version" to "Below 12.0".

export.png

Miscellaneous

  • Disable deprecation warnings: A new property property logging.deprecated.enabled xwiki.properties 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).

  • 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.

  • 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 https://velocity.apache.org/engine/2.2/changes.html 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

Upgrades

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

Translations

The following translations have been updated: 

Tested Browsers & Databases

Here is the list of browsers we support and how they have been tested for this release:

 BrowserTested on:
Chrome30.pngGoogle Chrome 79Jira Tickets Marked as Fixed in the Release Notes

Tests run and results
Edge30.pngMicrosoft Edge 79
Firefox30.pngMozilla Firefox 72Not Tested
IE30.pngInternet Explorer 11Not Tested
Safari30.pngSafari 13Not Tested

Here is the list of databases we support and how they have been tested for this release:

 DatabaseTested on:
hypersql.pngHyperSQL 2.5.0Not Tested
mysql.pngMySQL 5.7Not Tested
oracle.pngOracle 19cJira Tickets Marked as Fixed in the Release Notes

Tests run and results
postgresql.pngPostgreSQL 12

Here is the list of Servlet Containers we support and how they have been tested for this release:

 Servlet ContainerTested on:
tomcat-icon.pngTomcat 9.0.27Jira Tickets Marked as Fixed in the Release Notes

Tests run and results
jetty-icon.pngJetty 9.4.22 (XWiki Standalone packaging)
jetty-icon.pngJetty 9.4.22Not Tested

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
    • xwiki.properties
    • web.xml
    • hibernate.cfg.xml
  • Add xwiki.store.migration=1 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.0

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.
  • 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 xwiki.properties)
      • $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")).

Servlet 3.1 upgrade

XWiki now requires an application supporting Servlet 3.1 at least. This means for example that XWiki won't work in Tomcat 7 anymore.

API Breakages

The following APIs were modified since XWiki 11.10.2:

Failed to execute the [groovy] macro. Cause: [startup failed: Script1874.groovy: 9: unable to resolve class XmlSlurper  @ line 9, column 12.      result = new XmlSlurper().parseText(xml)                ^  1 error ]. Click on this message for details.

Credits

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

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected