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.

Mostly a stabilization release with bugs fixes and some improvement such as a better experience when translating pages, adding the possibility to set wiki macro priorities, new URLs for resetting passwords and retrieving usernames, and ability to disable the Like feature.

New and Noteworthy (since XWiki 13.0)

Full list of issues fixed and Dashboard for XWiki 13.1.

For Users

Improved explanation when creating a translation page

 
When editing a wiki page in-place you might have seen a "Translate" button if the edited page was missing a translation for the current locale. It wasn't obvious what this button does and the small notification message shown at the bottom of the page was hardly noticeable so we replaced it with a popover that is shown first when you enter edit mode and then whenever you hover the button. We also replaced the notification shown after clicking on the "Translate" button (to create the translation) with a popover on the page title input to invite you to translate the page title.

Empty Content Placeholder in WYSIWYG Editor

 
The WYSIWYG Editor shows a placeholder text when the edited content is empty and the text area is not focused. See the CKEditor Integration documentation for more information.

For Admins

Like feature disabling

 
It is now possible to disable the Like feature from the administration. Disabling it will preserve any existing Like data but hide them from the UI.

Miscellaneous

• New URL resource scheme for Reset password: The reset password and retrieve username features have been refactored to stop using wiki pages to work. The rationale is that these pages needed to be viewable by the guest user to work, thus making it impossible to protect the full wiki to guests (among other problems related to rights on these pages). Thus they have been re-implemented using dedicated URL schemes and components, and thus have had their URLs changed:

  • Reset password:
    • New URL: /xwiki/authenticate/reset 
    • Old URL: /xwiki/bin/view/XWiki/ResetPassword
  • Retrieve username:
    • New URL: /xwiki/authenticate/forgot 
    • Old URL: /xwiki/bin/view/XWiki/ForgotUsername

  The old XWiki.ResetPassword and XWiki.ForgotUsername wiki pages must not be used anymore, and any custom change perform in those pages won't be taken into account (you'll need to port your changes to Java since the new feature is coded in Java). However, the pages have been kept to ensure that using the old URLs will keep working for the time being: the pages now redirect to the new URLs.

For Developers

Wiki Macro priority

 
It's now possible to define the priority of a wiki macro (it used to only be possible for Java Macros). This is useful when you need your macro to be executed before or after other macros. When not specified the default priority is 1000.

Miscellaneous

• Controlling Transformations: It's now possible to control exactly which Rendering Transformations to execute when viewing a page. For example to execute only the macro transformation: http://localhost:8080/xwiki/bin/view/Sandbox/WebHome?transformations=macro.

• Allow to log deprecation warning in scripts: It's possible to log automatically a deprecation warning in a script, to inform users that some scripts might be removed in the future. This method checks the deprecation warnings configuration to only display the message if it is enabled.
  You can use it like this:

  ## First argument is the logger name, second is the message.
  $services.logging.deprecate("MyScript", "The script [MyScript] should not be used anymore")

  The output warning is displayed with a [DEPRECATED]  prefix.

• Raw Macro: When content is parsed, an XDOM tree is created. Sometimes you don't have any way to express the content you wish in that XDOM tree and you only wish that your content is output as is, when the XDOM is then rendered in a given syntax. You can use the raw macro for this need.

  Example:

  {{raw syntax="latex/1.0"}}
  \loadglsentries{glossary}
  \makeglossaries
  {{/raw}}

Upgrades

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

• Syntax Highlighting 4.6
• Jodconverter 4.4.2
• TrueVFS 0.14.0
• Solr 8.8.0
• MySQL connector 8.0.23
• MariaDB connector 2.7.2
• Joda-Time 2.10.10
• Infinispan 11.0.9.Final
• Checker Qual 3.10.0
• Byte Buddy 1.10.20
• Batik 1.14
• Apache XML Graphics Commons 2.6
• ASM 9.1
• CKEditor Integration 1.53.1

Translations

The following translations have been updated: 

• German
• Spanish
• French
• Norwegian

Tested Browsers & Databases

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

	Browser	Tested on:
	Google Chrome 88	Not Tested
	Mozilla Firefox 86	Not Tested
	Microsoft Edge 88	Jira Tickets Marked as Fixed in the Release Notes
	Internet Explorer 11	Not Tested
	Safari 14	Not Tested

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

	Database	Tested on:
	HyperSQL 2.5.1	Not Tested
	MySQL 8	Jira Tickets Marked as Fixed in the Release Notes
	Oracle 19c	Not Tested
	PostgreSQL 13	Not Tested
	MariaDB 10.5	Not Tested

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

	Servlet Container	Tested on:
	Tomcat 9.0.43	Jira Tickets Marked as Fixed in the Release Notes
	Jetty 9.4.29 (XWiki Standalone packaging)	Not Tested
	Jetty 9.4.29	Not Tested

Known issues

• Bugs we know about

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 13.1

Breaking OfficeConverter API

The interface org.xwiki.officeimporter.converter.OfficeConverter has been broken on purpose after an accepted proposal on the forum. This API was going to be broken because of the Jodconverter upgrade since the maintainer of the project moved their APIs to another package, so we took the opportunity to stop exposing in OfficeConverter classes coming from Jodconverter. Note that we introduced some new APIs to cover the usages we've seen for this API. Don't hesitate to open a feature request on Jira if some usages are not covered.

Also note that we discovered after the release that a legacy dependency was missing in the release for OfficeViewer interface. See the related ticket: https://jira.xwiki.org/browse/XWIKI-20555

New Reset Password and Retrieve Username URLs

See above for more details. The old XWiki.ResetPassword and XWiki.ForgotUsername wiki pages must not be used anymore, and any custom change perform in those pages won't be taken into account (you'll need to port your changes to Java since the new feature is coded in Java). However, the pages have been kept to ensure that using the old URLs will keep working for the time being: the pages now redirect to the new URLs.

Downgrade of Pygments from 2.5.1 to 2.4.2

We've identified some issues with the code macro when the language property is left undefined. The language can be miss-identified, leading to a bad syntax highlighting.

For example:

This issue has been introduced in Pygments 2.5.1 and fixed in Pygments 2.8.0 (see the Pygments changes for me details). We cannot upgrade to Pygments 2.8.0 for now since it requires Python 3, which we do not support currently. If you wish to keep using Pygments 2.5.1, you can do so by replacing the Pygments jar located in webapps/xwiki/WEB-INF/lib/pygments-2.4.2.jar with the the jar of Pygments 2.5.1.

API Breakages

The following APIs were modified since XWiki 13.0:

• This API has been removed to avoid future issues with the exposure of Jodconverter classes when upgrading. Some API have been introduced that should cover most of the usecases.
  • Violation type:
    java.method.removed
  • Code:
    ## Old:
    method org.jodconverter.document.DocumentFormatRegistry org.xwiki.officeimporter.converter.OfficeConverter::getFormatRegistry()
• AuthenticationConfiguration has only been moved to a new package, so it should not be breaking for people using this API in scripts.
  • Violation type:
    java.method.returnTypeChanged
  • Code:
    ## Old:
    method org.xwiki.security.authentication.api.AuthenticationConfiguration org.xwiki.security.authentication.script.AuthenticationScriptService::getAuthenticationConfiguration()
    
    ## New:
    method org.xwiki.security.authentication.AuthenticationConfiguration org.xwiki.security.authentication.script.AuthenticationScriptService::getAuthenticationConfiguration()
• Not a breakage. Annotation has been replaced by an entry in web.xml.
  • Violation type:
    java.annotation.removed
  • Code:
    ## Old:
    class com.xpn.xwiki.web.LegacyActionServlet
    
    ## New:
    class com.xpn.xwiki.web.LegacyActionServlet

Credits

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

Björn Ludwig
Christian Böhnke
ClemDee
Clément
Eduard Moraru
Francisco García Moreno
Jarle Sandmo
Manuel Leduc
Marius Dumitru Florea
Simon Urli
Thomas Mortagne
Vincent Massol
xrichard
XWiki