Mandatory document initializers and display properties for XWikiPreferences and in general

Development
1

Hi everyone,

while trying to fix XWIKI-24065 I noticed further discrepancies between the mandatory document initializer and the XWikiPreferences page in the XAR.

First, the plugins property is missing. I guess it should be added, too?

Second, the mandatory document initializer currently doesn’t set any custom displayers or also the picker or sort properties for ListClass. This has the consequence that they remain unset in the XClass definition and are only set when the XAR is imported. As we’re never updating this document from the XAR, this creates the following problems:

  1. New fields cannot have non-default values for picker, sort, or custom displayers.
  2. Existing values are never updated.

In particular the second one is very bad as it means that bug fixes including security fixes for custom displayers will never be applied.

I also discovered that just adding all non-default values now might create new problem in the future: What if we remove them again in a future version? This removal won’t be applied on an update. So we should probably explicitly set all values.

I have therefore the following proposal:

  1. Change this behavior and ensure that mandatory document initializers always create complete XClass definitions where all meta properties are set. This might have unintended consequences if another XClass exist both in a mandatory document initializer and a XAR or if an XClass has actually been customized.
  2. Change this behavior at least for XWikiPreferences to ensure that all users have the correct XClass definition, duplicate the display code in the mandatory document initializer and also initialize all other properties like picker and sort.

Note that while the code duplication is bad, I have a quite thorough page test now to catch any deviation between the XAR and the mandatory document initializer, and thanks to the fact that generating a bit more code is cheap with AI, it even produces a readable diff that shows the exact differences in case there are any: XWIKI-24065: underline property is not initialized automatically in XWikiPreferences for upgraded instances by michitux · Pull Request #5338 · xwiki/xwiki-platform · GitHub

Do you have any thoughts on this? I think we should also differentiate between the LTS branch and the master branch.

Thank you very much!

2

I don’t know enough to give an informed feedback, but the plan looks ok on paper.
I guess at risk of breaking stuff, but necessary nonetheless.

3

Sorry for the delay, I had to think more about that proposal.

This is supposed to be a feature. The point of xclass initializers was mostly to make sure the data format is right (since that’s the only thing that matters on Java side), and allow more advanced display stuff to be provided by a XAR or customized.

The XWikiPreference case is very specific and became a huge pain because that document mix way too many things which ideally should have different behaviors at upgrade.

I feel a better would be to introduce slightly more fine-grained way to control upgrade behavior for entity types: for example being able what exactly in a document is upgradable (in XWikiPreferences, the xclass) and what is not (in XWikiPreferences, most xobject types).

Another possibility would be to also introduce upgrade behavior configuration at xclass level: the XWikiPreferences document would have the default entity type (so upgradable), but then we would configure xclasses like XWikiPreferences, XWikiGlobalRight and XWikiRight so that upgrading those xobjects is not allowed (but the xclasses themself would be).