Skip to Content

Upgrade Feedback (10.x)

Last modified by Vincent Massol on 2024/11/19 16:15

 XWiki
 Requirements
 Completed
 
 
 

Description

Requirements

 We regularly see users having problems to upgrade (cf forum, irc, mailing lists) and we’d need to list the common issues they have. Their problems may not be related to the UI but to bugs/limitations we currently have. 

Error

Top 5 Usability issues we need to fix

Selection made by @evalica:

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

New features / improvements that need design proposals

  • Invalid extensions step: step in DW that display the invalid extensions and ask the user to remove them.
  • Environment validation step: step in the beginning of DW that validates the configuration found locally and suggest improvements in order for the instance to work properly.

User Feedback

 Need runnning as a deamon, better upgrade process with no data loosing

 Better upgrade process. Still very manual.

 Change it to a software for normal users/admins with easy installation, update and backup features and combine it with an appserver by delivery

  • Upgrade seen as a lengthy / complicated process

Top 5 Voted Issues

  • 7 votes
    Failed to execute the [groovy] macro. Cause: [startup failed: Script3287.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.
  • 4 votes
    Failed to execute the [groovy] macro. Cause: [startup failed: Script3288.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.
  • 3 votes
    Failed to execute the [groovy] macro. Cause: [startup failed: Script3289.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.
  • 2 votes
    Failed to execute the [groovy] macro. Cause: [startup failed: Script3290.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.
  • 2 votes
    Failed to execute the [groovy] macro. Cause: [startup failed: Script3291.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.

Ideal upgrade (Features)

UC: When starting an upgrade, everything will be automated, and users are provided a life preview of how the upgrade will look like (main wiki, subwikis, etc.). The administrator can browse and see the live instance, and if he likes the changes and validates there are no problems, he would press an "Apply" button.
  • We could replicate the virtual machine containing the instance; OR duplicate the folders, database, workdir and provide a way to make the dry run.
Warning

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

Information

Related proposal: Extension Updater

UC: Before upgrading provide a status of the instance / wikis. Have a report showcasing what are the customisations made to that particular instance (custom skins, custom applications, pages changes, custom configurations, etc.). This would warm about the magnitude / duration / success of the future upgrade. We could display like a percentage of customisation, like "Your wiki is 45% Vanilla". It could also detect if the wiki has custom applications (some might have dependant .jars).
UC: Have Artificial Intelligence inside XWiki that studies what decisions you take during a particular upgrade, learns from them, and will be able to apply similar decisions on the future upgrades it will make. For example, if we always do MERGE on WebPreferences, if will apply this decision on all WebPreference pages.
Warning

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

UC: Be able to make diffs also on the WAR. Currently only UI/Extensions/Pages have the DW step and showcase the diffs. For the WAR you still need to do manual diffs from the filesystem's console. We should see what are the new files, the missing files, and the files that have differences. The diff on configuration files is the minimal thing we can do.
Warning

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

Thomas: Upgrading the WAR from the wiki - impossible to do in a generic way. Easy in Debian, but no equivalent for other distro. List of environments. Easy to do with Jetty (demo - useless). XWiki doesn't have enough rights to proper install itself, cannot modify its own files. 

UC: Provide support for custom Skins. There are a lot of manual operations that need to be done for custom Skins. Some local templates need to be overwritten, or Fonts files need to be manually added. Also some templates might be attached to pages that have XWikiSkins objects. Same case for customised PDF Exports. Sometimes xhtml2fo.xml files are attached to wiki pages that contain PDFTemplate objects.

Needing improvements in

Merging Configuration files

  • Recommendation: Browse all the release notes from your version X to Y to see if there are things to modify.
  • Automatically managing configuration changes
  • Differences between Docker and Webapp update method:
    • Idea: Merge the configuration files and provide a differences view (either manually [GitHub+WinMerge] or from the DW).
    • Idea: Docker: "update script that does the copy and to copy also the original files and/or provide a diff or even better do the merge as we do it in the debian distribution" (Vincent).
Warning
  • Forum entry (Differences between Docker and Webapp)
  • Forum entry (Apply release notes issues specific to a particular version)
Information

Idea (Thomas): 

  • Environment validation step (java version, OS, configuration, etc.)
  • Configuration Checker: Check and validate the configuration in the beginning of DW (+ provide info and documentation on where to change). Suggest bigger memory (+give link to documentation), etc. 

Configuration values

Common configuration values for "production-ready" wikis (we might want to change / update the default values):

  • Tomcat java opts variable
    • -Xmx1024m is not enough (edit setenv.sh)
  • LDAP Authentication
    • Install LDAP App 
    • Configurations
      • xwiki.authentication.authclass=org.xwiki.contrib.ldap.XWikiLDAPAuthServiceImpl
      • xwiki.authentication.ldap.trylocal=1
  • TLS/SSL configuration for Tomcat
  • Short URLs
  • Other:
    • xwiki.plugin.watchlist.automaticwatch=none
    • xwiki.plugin.image.defaultQuality = 0.8
    • openoffice.homePath and autostart
    • rendering.imageDimensionsIncludedInImageURL = false
    • Adding markdown to xwiki.rendering.syntaxes
    • Cache configuration xwiki.store.cache.capacity=500
Warning

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

Thomas: Very hard to provide a configuration file that will satisfy all the cases. We could modify the jetty one, but that's only for demo purposes.

Database

  • SOLR data is not deleted when upgrading XWiki docker image
Warning

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

Old Java

  • We should update our Java version need to run XWiki. Currently max is 8.
Warning
Information

Action to take: XWiki on Java 11.0

Launching DW

  • DW is not launched in some cases. Solutions to manually trigger it or prevent accidental skipping.
Warning

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

Information

Proposal: DW Never Button

Upgrade Issues / Bugs (2017 - 2018)

Configurations

Conflicting old configurations

  • Some remaining configurations from the early versions which were incompatible with the current version
Warning
  • XS*6-9280 (XWiki 6.4.4 - 7.4.3)

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

Storage / Database attachment

  • Having deprecated pre 9.9 configurations
    xwiki.store.attachment.recyclebin.hint=file
  • DW didn't add the XWiki.Extensions page, because of an attachment
  • Many attachments reported missing after upgrade. Useful Attachment Checker.
  • After the upgrade, the attachments disappeared. 
  • Can’t find descriptor for the component
Information
  • We could at least have an FAQ entry
  • Improve the Release Notes app to list the breakages and configuration changes between versions
Warning

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

Warning

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

  • Changing the default theme logo, that attachment blocked the DW installation process.
Warning

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

Customisations

PDF Export

  • PDF Export broken. Needs 3 way merge for xhtml2fo.xsl
  • Different PDF Export after upgrade caused by bugs in dependencies + manual need to copy FONTS. PDFTemplate and Skins should be treated specially. 
Warning
  • C*2-2453 (XWiki 8.4.5)
  • XNS*6-3672 (XWiki 7.4.4)

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

Information

Action to take: Better PDF export by making it easily customizable. We could investigate what are the regular customizations. 

Database

  • Checking database sanity. 
  • Make sure the database has been migrated too (issues when schema comes from old version < 3.2)
  • "Failed updating schema"
Warning

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

We already have some migration tests + docker will help do tests on multiple configurations.

Extensions

Some extensions not working properly

  • "certain macros are broken (doctree), breadcrumbs are broken in the header section, and editing pages gives me a infinite spinning circle. If I spin down this instance, change the port number back to port 8080, then spin the instance back up, everything will work as intended."
    • Issue: "all the JavaScript code and the CSS styles are being cached by your browser. Try to clear the browser cache."
  • "after upgrade, all the subpages under my wiki are gone, so are those things under Navigation"
    • "So make backups and make Shift + F5 your friend (at least until whatever the issue is gets fixed)"
Information

Action to take: Fix the resources versioning

Warning

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

Conflicting old extensions

Information

Idea (Thomas): 

  • Invalid extensions step: too much oriented towards outdates extensions. It's not listing invalid extensions so that they could be uninstalled. Should be redesigned to be about INVALID extensions and how you can fix them. DESIGN: How to show invalid extension and what to do with them? What do we let the users do and what we show to the users. 
  • Redesigning Invalid Extensions Step: list dependencies. extension that is not needed anymore, because it's not a dependency anymore, not part of the flavor anymore. Clean-up step. Similar to Ubuntu - packages not needed anymore - ask to remove. Blog as example. 
  • SEARCH: Having old Lucene Search Application installed, although it was replaced by the Solr Search Application some time ago. Needs manual uninstall.
Warning

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

  • BLOG
    • Cannot upgrade Blog
    • Stale dependency
Warning

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

  • NOTIFICATIONS
    • Missing notification properties in user objects
    • Duplicate versions (one installed in a subwiki not specified)
Warning

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

Upgrading bundled Contrib extensions

Information
  • For some extensions (like CKEditor) users are manually reminded to upgrade those extensions in intermediary versions
Information

Idea (Thomas): Have a Local Index that contains all the local repositories and search in them. This would allow fast searching + will be able to do a lot more filtering to determine only valid extensions that could be proposed to upgrade.
Failed to execute the [groovy] macro. Cause: [startup failed: Script3308.groovy: 14: unable to resolve class XmlParser  @ line 14, column 12.     def xml = new XmlParser().parseText(cont)               ^  1 error ]. Click on this message for details.

Warning
  • Issues fixed by upgrades examples: XNS*6-3865

Upgrading extensions installed 'on farm'

  • Some issues with extensions installed "on farm" or partially installed that have XAR dependencies from platform (example CKEditor 1.19)
  • Manually upgrading the extensions installed "on farm" before proceeding to upgrade the wikis.
    • Apparently what Extension Manager does when it has to replace an extension with an "on farm" installation is that it applies "Uninstall" on each wiki and then re-installs the extension as "on farm". 
Warning
  • XNS*6-3435 (XWiki 6.4.6, 5.4.6 - 6.4.8)

Users

Missing some user rights

  • XWiki admin user is removed from the XWikiAdminUser group. Rights are lost. Macros are broken.
    "The execution of the
[velocity] script macro is not allowed. Check the rights of its last author
or the parameters if it's rendered from another script"
  • The best practice in DW when dealing with WebPreferences pages is to automatically apply MERGE
Warning

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

Already fixed by defining in the .pom file the entry type, mentioning what pages are protected in the upgrade. 

Translations

  • Wiki Manager missing translations registered with a GLOBAL scope (hence requiring Programming Rights).
Warning

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

Information

Action to take (Thomas): "fix the Programming Rights issue on subwikis - example: myxwiki.org admin with broken pages that need PR (fix PR pages in XS, but extensions could have problems too)"

  • Some way to give PR to anyone who would like to install a specific extension. Trusted extensions (or version) that could be installed with superadmin. 
  • Wiki Status: See broken pages that have PR needed: status of those pages || broken wiki components. 

Downgrades

  • By request or by mistake
Warning
{{/html}}

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected