Wiki source code of Release Notes for XWiki 5.2

Last modified by Thomas Mortagne on 2017/03/24

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 This is the release notes for [[XWiki Commons>>http://commons.xwiki.org]], [[XWiki Rendering>>http://rendering.xwiki.org]], [[XWiki Platform>>http://platform.xwiki.org]] and [[XWiki Enterprise>>http://enterprise.xwiki.org]]. They share the same release notes as they are released together and have the same version.
6
7 {{warning}}
8 **The support of XWiki Enterprise Manager is stopped**. XWiki Enterprise now comes with the ability to create (sub)wikis by default, see below.
9 {{/warning}}
10
11 {{error}}
12 We've discovered several important regressions in this version after it was released:
13 * Several RSS feed regression ([[XWIKI-9576>>https://jira.xwiki.org/browse/XWIKI-9576]] and [[XWIKI-9610>>https://jira.xwiki.org/browse/XWIKI-9610]]): Makes some RSS readers show duplicate entries (for readers who use a Feed entry's URL as its unique id).
14 * [[a Watchlist regression>>https://jira.xwiki.org/browse/XWIKI-9601]]: Links in the HTML email sent by the Watchlist do not work anymore.
15 * Any Scheduler job that computes external URLs will have the generated URL be empty.
16 * [[Image attachments don't appear in the PDF export if their URL contains special characters>>https://jira.xwiki.org/browse/XWIKI-9611]].
17 * PDF export missing images
18 * Custom property displayers are not applied any more in view mode on the user profile page ([[XWIKI-9652>>https://jira.xwiki.org/browse/XWIKI-9652]] and [[XWIKI-9653>>https://jira.xwiki.org/browse/XWIKI-9653]]) and links from the ##comment## and ##address## user profile fields are broken ([[XWIKI-9655>>https://jira.xwiki.org/browse/XWIKI-9655]])
19
20 They are fixed in XWiki 5.2.1/5.2.2 and later.
21 {{/error}}
22
23 This release comes with multiwiki support enabled by default: users are able to create new wikis without the need to install additional extensions. This is possible because the Workspace Application has been integrated in XWiki Enterprise. We stopped the support for XWiki Enterprise Manager as a consequence. Apart from this, the new release brings a Solr-based live search (to replace the one based on Lucene) and the ability to track active XWiki installs. The Distribution Wizard has a new step to upgrade all wikis. Developers will be interested by the new Wiki Stream framework which can already be used to export large wikis in XAR format. A lot of bug fixes (135) and many improvements (50) complete this release and make it worth trying.
24
25 = New and Noteworthy (since XWiki 5.1) =
26
27 [[Full list of issues fixed and Dashboard for 5.2>>https://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=11602]].
28
29 == Multi-wiki Support ==
30
31 XWiki Enterprise comes now with the ability for users to create their own wikis (a.k.a subwikis) without the need to install additional extensions. This supersedes the notion of "workspace" and consists in the integration of the [[Workspace Application>>extensions:Extension.Workspace Application]] in the default XWiki distribution.
32
33 {{image reference="[email protected]"/}}
34
35 This new menu entry appears only if a wiki template is created first, see below.
36
37 === Wiki Creation Right ===
38
39 The wiki creation is now possible for users who have the "createwiki" right. This right is only available for the main wiki users, exactly like the Programming Right.
40
41 === Wikis Administration Section ===
42
43 A new section is available in the administration of the main wiki. In this section, you can enable the wiki creation feature by creating a wiki template. It also manages who has the right to create new wikis.
44
45 {{image reference="[email protected]"/}}
46
47 === Wiki Creation Wizard ===
48
49 A new wizard for the creation of a new wiki is now available from the "Add" menu.
50
51 {{image reference="[email protected]"/}}
52
53 {{image reference="[email protected]"/}}
54
55 === Home Menu ===
56
57 A new top level menu is available when there is more than one wiki.
58
59 {{image reference="[email protected]"/}}
60
61 {{image reference="[email protected]"/}}
62
63 The "main wiki" (the first you have when you start a new instance) is now called "**Home**".
64
65 == Solr-based Search Suggest ==
66
67 Starting with this version the [[search suggest>>doc:extensions:Extension.Search Application||anchor="HSearchSuggest"]] feature takes into account the configured search engine. To achieve this we added a new property to ##SearchSuggestSourceClass## that specifies the search engine used by the source. We also created a search suggest service based on Solr and we added search suggest sources that mimic the behaviour of the existing Lucene-based sources. As a result, the search suggest feature is now using Solr by default (as Solr is the default search engine starting with 5.1).
68
69 We also improved the search suggest administration section
70
71 {{image reference="[email protected]"/}}
72
73 and we simplified the source creation form.
74
75 {{image reference="[email protected]"/}}
76
77 The live search now displays a message when there are no results.
78
79 {{image reference="[email protected]"/}}
80
81 == Distribution Wizard Step to Upgrade All Wikis ==
82
83 We added a new step to the [[Distribution Wizard>>doc:platform:Features.DistributionWizard]] to update the default set of wiki pages on each of the existing wikis. This step is triggered only if you choose to upgrade the entire farm in the "Upgrade Mode" step.
84
85 {{image reference="[email protected]" width="600px"/}}
86
87 == Active Installs Tracking ==
88
89 It' very important for the open source committers to understand how well or how badly they're faring when developing the XWiki open source project. So far we didn't know if the number of people using XWiki was increasing, decreasing or staying stable. This module allows us to know who's using XWiki.
90
91 It does the following:
92
93 * A client side JAR is bundled with XWiki and it sends a ping with data once per day
94 * A server side Application is installed on xwiki.org, allowing us to query the data sent and to display a counter of Active Installs of XWiki (i.e. installs for which we've received a ping in the last N days, for example at least one ping in the past month).
95
96 The data sent is anonymous and consists of the following:
97
98 * A unique id (UUID) representing the XWiki instance. Note that not even the IP is kept and there's no way to find who's having a give UUID (it's generated using Java's UUID implementation)
99 * The date of the ping
100 * The XWiki distribution id (e.g. ##org.xwiki.enterprise:xwiki-enterprise-web##)
101 * The version of your XWiki distribution (e.g. ##5.2##)
102 * The technical ids and versions of extensions you have installed.
103
104 This will allow us to present the following data:
105
106 * Number of total installs of XWiki
107 * Number of Active Installs
108 * Most used extensions across versions of XWiki
109 * How frequently the XWiki user base upgrades to newer versions of XWiki
110
111 {{image reference="[email protected]"/}}
112
113 {{info}}
114 In the near future we'll offer a UI feature to opt-out (in the Administration pages) but at the moment if you wish to opt-out (please don't, we need your help, knowing who's using us and that it's growing is what keeps us motivated to continue developing XWiki!), then simply remove the ##WEB-INF/lib/xwiki-platform-activeinstalls*## JAR and restart.
115 {{/info}}
116
117 Reference documentation:
118
119 * [[Client side module>>extensions:Extension.Active Installs Client API]].
120 * [[Server side module>>extensions:Extension.Active Installs Server Application]].
121
122 == Toggle Email Address Obfuscation ==
123
124 The email configuration section in the [[Administration>>doc:extensions:Extension.Administration Application]] now has an option to enable/disable the obfuscation of the email addresses that are stored in object properties of [[type Email>>ReleaseNotes.ReleaseNotesXWiki42||anchor="HNewfieldtypesforemailandlistofpages"]]. The obfuscation is done by displaying only the first letter of the email account, e.g. //[email protected]//, the rest of the letters being replaced by an ellipsis. Email obfuscation is off by default.
125
126 {{image reference="[email protected]"/}}
127
128 == Markdown Syntax 1.1 ==
129
130 We've added [[version 1.1 of the Rendering Syntax for Markdown>>rendering:Main.Markdown11]], adding support for:
131
132 * Macros
133 * Superscript and subscript
134 * (X)HTML improvements
135
136 == Export Large Wikis as XARs ==
137
138 It's possible to enable the use of new [[WikiStream>>doc:extensions:Extension.WikiStream Module]] framework in standard export action (used in the standard export UI for example). Among other things it allows exporting a wiki of pretty much any size.
139
140 [[WikiStream>>doc:extensions:Extension.WikiStream Module]] is too young to be enabled by default and will require heavy testing. In the meantime you can try it by uncommenting {{code}}#xwiki.action.export.xar.usewikistream=1{{/code}} at the end of xwiki.cfg file.
141
142 == Miscellaneous ==
143
144 * The blog application is now packaged by default in the Home wiki only (not in new wikis).
145
146 {{error}}
147 In the case you are using the blog application in your subwiki, **the upgrade might remove it**. You will have to **install the blog application again** through the [[extension manager>>extensions:Extension.Extension Manager Application]], but **you should take care if you have customized it**.
148 {{/error}}
149
150 * {{id name="userVerticalMenu"/}}The user profile menu is now consistent with the administration menu.(((
151 {{image reference="[email protected]"/}}
152 )))
153 * The ##line## [[chart>>doc:extensions:Extension.Chart Macro]] type has two parameters, ##hideShapes## and ##hideLines##, to hide the shapes used to display the data points or to hide the interpolation lines that connect the data points.(((
154 {{image reference="[email protected]"/}}
155 )))
156 * When creating or editing a [[template provider>>doc:extensions:Extension.Administration Application||anchor="HCreatethetemplateprovider"]] the template name field is now mandatory.(((
157 {{image reference="[email protected]"/}}
158 )))
159 * The checkboxes for the global rights settings are now displayed on the left of their labels.(((
160 {{image reference="ReleaseNotesXWiki52RC1@RightsAdministration-CheckboxOnTheLeft.png"/}}
161 )))
162 * The "Create a new wiki" link has been removed from the wiki index. Now, you can only use the //Add > Wiki// menu.
163 * The Distribution Wizard does not appear anymore just after creating a new wiki based on the default template.
164
165 See the [[full list of JIRA issues>>https://jira.xwiki.org/sr/jira.issueviews:searchrequest-printable/temp/SearchRequest.html?jqlQuery=project+in+%28XCOMMONS%2C+XRENDERING%2C+XWIKI%2C+XE%29+and+status+%3D+Closed+and+resolution+%3D+Fixed+and+fixVersion+in+%28%225.2-milestone-1%22%2C+%225.2-milestone-2%22%2C+%225.2-rc-1%22%2C+%225.2%22%29&tempMax=1000]] fixed in this release.
166
167 = For Developers =
168
169 == JSON Parsing in Velocity ==
170
171 ##$jsontool.parse('["json string"]')## can now be used to parse a serialized JSON into [[json-lib>>http://json-lib.sourceforge.net/]] [[arrays>>http://json-lib.sourceforge.net/apidocs/jdk15/net/sf/json/JSONArray.html]] or [[objects>>http://json-lib.sourceforge.net/apidocs/jdk15/net/sf/json/JSONObject.html]].
172
173 Only valid JSON strings can be parsed. JSONP is not supported. If the argument is not valid JSON, then ##null## is returned, parsing exceptions are caught.
174
175 == Query String Escaping ==
176
177 The following method ##$escapetool.url(Map<String, ?>)## has been added to the escapetool module. It allows to create a properly URL-escaped query string from a map of parameters. The key in the map is the parameter name and the value can be an object, an array of objects or a collection of objects. ##String.valueOf(Object)## is used to serialize the objects (values). For example ##$escapetool.url({'alice': ['A&A', 'M&M'], 'bob': [13, 27]})## would return ##alice=A%26A&alice=M%26M&bob=13&bob=27##. See [[XCOMMONS-435>>https://jira.xwiki.org/browse/XCOMMONS-435]].
178
179 == New XWikiDocument API to Remove an Attachment ==
180
181 ##XWikiDocument#deleteAttachment## methods have been deprecated in favor of the combination of ##XWikiDocument#removeAttachment## and ##XWiki#saveDocument##. This make attachment deletion follow the same behavior as xobject and among other things allow doing all sort of modifications to a XWikiDocument without touching the database until we decide to apply them by saving the document.
182
183 == Choosing which types of attachments can be displayed inline (Security) ==
184
185 In order to prevent XSS via FileUpload, a new feature has been added : you can now specify in xwiki.properties which types of attachment can be displayed inline.
186 In the "Attachment" section of xwiki.properties, you can either precise a whitelist of mimetypes that can be displayed inline, or precise a blacklist of mimetypes that shouldn't be displayed inline (if you use this configuration, it is strongly advised to blacklist at least "text/html" and "text/javascript" mimetypes for security reasons).
187 Note that attachments provided by users having Programming Rights won't be affected by these restrictions.
188
189 == Forcing IE Compatibility Mode ==
190
191 Now, we force the Compatibility mode for Internet Explorer (IE) browsers to use the latest rendering mode.
192 Before, the IE browser displayed all intranet sites in compatibility mode by default. This means that even if the user was using IE9, he saw the content rendered with IE7 standards. Since we don't [[support>>dev:Community.BrowserSupportStrategy]] IE6/7 anymore this lead in displaying broken layout, scrollbars, etc. See [[XWIKI-8907>>https://jira.xwiki.org/browse/XWIKI-8907]].
193
194 == New Filter Module ==
195
196 Commons has a new core module for all streaming systems based on filters like Rendering and the [[Wiki Stream>>doc:extensions:Extension.Wiki Stream Module]]. See [[Filter Module documentation>>extensions:Extension.Filter Module]].
197
198 == New Wiki Stream Framework ==
199
200 Wiki Stream goal is to provide generic API to make easier for different representations of a wiki instance to communicate with each other.
201
202 It's still in a very early stage and the API might change during 5.x but it's already pretty complete and usable.
203
204 The the following streams modules are provided in 5.2:
205
206 * XWiki instance input (send WikiStream events from various data of the XWiki instance like the documents in the database etc.)
207 * XWiki instance output (generate and save various data of the XWiki instance like the documents from WikiStream events)
208 * XAR instance output (write a XAR package from WikiStream events)
209 * XAR instance input (generate WikiStream events from a XAR package)
210
211 == New Eclipse CS Extension ==
212
213 [[XCOMMONS-353>>https://jira.xwiki.org/browse/XCOMMONS-353]] made our checkstyle.xml file unusable as it is in Eclipse cs because of the custom rule that could not be found in the Eclipse classpath.
214
215 ##xwiki-commons-tool-verification-resources## module is now also an Eclipse cs extension which mean you can just drop its jar in Eclipse ##plugins/## folder and you will get the XWiki checkstyle configuration listed in the standard configurations.
216
217 == Deprecated and Retired projects ==
218
219 * Google plugin (##com.xpn.xwiki.plugin.google.GooglePlugin##) has been retired, you can find it on https://github.com/xwiki-contrib/retired/tree/master/xwiki-platform-google-plugin
220
221 == Upgrades ==
222
223 The following dependencies have been upgraded:
224
225 * Aether 0.9.0.M2 (moved from org.sonatype.aether to org.eclipse.aether)
226 * CSSParser 0.9.9
227 * [[Groovy 2.1.7>>https://jira.xwiki.org/browse/XCOMMONS-445]]
228 * [[HSQLDB 2.3.0>>https://jira.xwiki.org/browse/XE-1323]]
229 * Infinispan 5.3
230 * JGroups 3.3.4
231 * Maven 3.1.0
232 * Tika 1.4
233 * Xerces2-Java 2.11.0
234
235 == Miscellaneous ==
236
237 * Added support for custom facets in Solr search API
238 * New [[Instance Module>>extensions:Extension.Instance Module]] used to compute a unique id for each XWiki instance (used by the [[Active Installs Client API>>extensions:Extension.Active Installs Client API]]
239 * The way to declare the type supported by a ##org.xwiki.properties.converter.Converter## component changed from role hint to generic type. See [[Properties Module documentation>>extensions:Extension.Properties Module||anchor="HConvertercomponent28Recommended29"]] for more details. The old way is still supported for retro-compatibility.
240 * Added DocumentReference and EntityReference property converters which makes possible to:
241 ** use them in rendering macros parameters beans (see [[How to write a macro>>rendering:Main.ExtendingMacro||anchor="HMacroCode"]])
242 ** in Velocity pass a String directly to a method requiring a DocumentReference or EntityReference
243 * Added new API to the JODA Time plugin to get an ISO8601 formatter.
244
245 = Translations =
246
247 The following translations have been updated:
248
249 {{language codes="ca, cs, da, de, es, fr, gl, it, ko, lv, nl, pl, pt, pt_BR, ro, ru, sk, sv, uk, vi, zh, zh_TW"/}}
250
251 = Tested Browsers & Databases =
252
253 {{include reference="TestReports.ManualTestReportXWiki52Summary"/}}
254
255 = Known issues =
256
257 * [[Bugs we know about>>https://jira.xwiki.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=category+%3D+%22Top+Level+Projects%22+AND+issuetype+%3D+Bug+AND+resolution+%3D+Unresolved+ORDER+BY+updated+DESC]]
258
259 = Backward Compatibility and Migration Notes =
260
261 == General Notes ==
262
263 When upgrading make sure you compare your ##xwiki.cfg##, ##xwiki.properties## and ##web.xml## files with the newest version since some configuration parameters may have been modified or added. Note that you should add ##xwiki.store.migration=1## so that XWiki will attempt to automatically migrate your current database to the new schema. Make sure you backup your Database before doing anything.
264
265 == Solr Index Format Change ==
266
267 If you're upgrading from XWiki 4.5.x to this version you'll need to perform a full re-indexation when using the Solr Search. To do this you have to delete the ##solr## folder from the configured permanent directory. This is needed because in XWiki 4.5.x the Solr search was experimental and we've completely changed the indexing format (i.e. the Solr schema) in XWiki 5.1.
268
269 == Email Address Obfuscation ==
270
271 In [[4.2>>ReleaseNotes.ReleaseNotesXWiki42||anchor="HNewfieldtypesforemailandlistofpages"]] we introduced a new object property type called Email that can be used to store email addresses. In [[5.1>>ReleaseNotes.ReleaseNotesXWiki51||anchor="HUseremail"]] we decided to use this new property type in the user profile to store the user email address. With this change we also introuced a defaut custom displayer for the Email property type that obfuscates the email address in view mode. As a consequence the user profile email address became obfuscated by default. Starting with 5.2 we allow you to toggle the email address obfuscation from the administration. What is important to know is that the email address obfuscation is off by default. So if you upgrade from 5.1 and you want to preserve the obfuscation then you need to enable it from the administration.
272
273 == Instance Identifier ==
274
275 XWiki now creates a unique identifier in the database (this is used by the new Active Installs module and will be used in the future by the Extension Manager to identify your instance for example). You need to verify that your ##hibernate.cfg.xml## file has the following mapping definition next to the existing mapping definitions:
276
277 (((
278 {{code}}
279 ...
280 <mapping resource="instance.hbm.xml"/>
281 ...
282 {{/code}}
283 )))
284
285 == Multi-Wiki ==
286
287 When you upgrade from an old XEM farm, you might not have the user interface to handle multi-wiki just after the upgrade. In this case, just go in the "Wikis" section of the administration (in the main wiki), and click to "create a template first" in the "Wiki Template" subsection. It should fix the issue.
288
289 == API Breakages ==
290
291 The following APIs were modified since XWiki 5.1:
292
293 * Moved to ##xwiki-commons-legacy-properties##
294
295 {{code language="none"}}
296 org.xwiki.properties.converter.AbstractCollectionConverter: Class org.xwiki.properties.converter.AbstractCollectionConverter removed
297 {{/code}}
298
299 * This method should never have existed
300
301 {{code language="none"}}
302 org.xwiki.rendering.listener.reference.ResourceType: Method 'public void setScheme(java.lang.String)' has been removed
303 {{/code}}
304
305 * Moved from ##xwiki-rendering-api## to ##xwiki-rendering-xml##
306
307 {{code language="none"}}
308 org.xwiki.rendering.renderer.printer.XHTMLWikiPrinter: Class org.xwiki.rendering.renderer.printer.XHTMLWikiPrinter removed
309 org.xwiki.rendering.renderer.printer.XMLWikiPrinter: Class org.xwiki.rendering.renderer.printer.XMLWikiPrinter removed
310 {{/code}}
311
312 * This field is not meant to be be modified, the final was just forgotten.
313
314 {{code language="none"}}
315 com.xpn.xwiki.XWikiContext: Field TYPE_PROVIDER is now final
316 {{/code}}
317
318 * Not an API. This should be internal.
319
320 {{code language="none"}}
321 com.xpn.xwiki.store.XWikiHibernateBaseStore: Method 'protected java.lang.String[] addHibernateSequenceIfRequired(java.lang.String[], java.lang.String, org.hibernate.Session)' has been removed
322 {{/code}}
323
324 * Has been moved to ##xwiki-platform-feed-api## since it was the only module using it. We also dropped jTidy in favor of HTMLCleaner.
325
326 {{code language="none"}}
327 com.xpn.xwiki.util.TidyMessageLogger: Class com.xpn.xwiki.util.TidyMessageLogger removed
328 {{/code}}
329
330 * Google API plugin has been retired
331
332 {{code language="none"}}
333 com.xpn.xwiki.plugin.google.GooglePlugin: Class com.xpn.xwiki.plugin.google.GooglePlugin removed
334 com.xpn.xwiki.plugin.google.GooglePluginApi: Class com.xpn.xwiki.plugin.google.GooglePluginApi removed
335 {{/code}}
336
337 * Return the number of imported documents
338
339 {{code language="none"}}
340 com.xpn.xwiki.tool.backup.Importer: Return type of method 'public void importXAR(java.io.File, java.lang.String, com.xpn.xwiki.XWikiContext)' has been changed to int
341 {{/code}}
342
343 * The JPQLParser generates source code (that should be internal but it is not) and the grammar has changed a bit.
344
345 {{code language="none"}}
346 org.xwiki.query.jpql.analysis.Analysis: Method 'public void caseAFuncnumComparableItem(org.xwiki.query.jpql.node.AFuncnumComparableItem)' has been added to an interface
347 org.xwiki.query.jpql.analysis.Analysis: Method 'public void caseAFuncstrComparableItem(org.xwiki.query.jpql.node.AFuncstrComparableItem)' has been added to an interface
348 org.xwiki.query.jpql.analysis.Analysis: Method 'public void caseAFunctimeComparableItem(org.xwiki.query.jpql.node.AFunctimeComparableItem)' has been added to an interface
349 org.xwiki.query.jpql.analysis.Analysis: Method 'public void caseAPathComparableItem(org.xwiki.query.jpql.node.APathComparableItem)' has been added to an interface
350 org.xwiki.query.jpql.node.AGroupbyItem: Parameter 1 of 'public AGroupbyItem(org.xwiki.query.jpql.node.PPath)' has changed its type to org.xwiki.query.jpql.node.PComparableItem
351 org.xwiki.query.jpql.node.AGroupbyItem: Method 'public org.xwiki.query.jpql.node.PPath getPath()' has been removed
352 org.xwiki.query.jpql.node.AGroupbyItem: Method 'public void setPath(org.xwiki.query.jpql.node.PPath)' has been removed
353 org.xwiki.query.jpql.node.AOrderbyItem: Parameter 1 of 'public AOrderbyItem(org.xwiki.query.jpql.node.PPath, org.xwiki.query.jpql.node.TOrderbySpec)' has changed its type to org.xwiki.query.jpql.node.PComparableItem
354 org.xwiki.query.jpql.node.AOrderbyItem: Method 'public org.xwiki.query.jpql.node.PPath getPath()' has been removed
355 org.xwiki.query.jpql.node.AOrderbyItem: Method 'public void setPath(org.xwiki.query.jpql.node.PPath)' has been removed
356 {{/code}}

Get Connected