Description

• • Plan of action
  • Details on the implementation of each task
    • Task 1: Introduce CSS equivalents for all LESS variables
    • Task 2: Migrate most of XWiki's LESS files to native CSS
    • Task 3: Deprecate the use of new LESS and LESS variables
    • Task 4: Propose a tool to convert LESS files to CSS
    • Task 5: Migrate the public extensions to use only LESS
    • Task 6: Drop support for LESS in XWiki

Plan of action

This plan of action was discussed quickly in https://forum.xwiki.org/t/proposal-moving-away-from-less/15881 , it is subject to change and it's only a guide to move in the right direction. Each step of the plan have a specific jira task related to it (except for 5. which is too vast for this kind of modelization).

The tasks are described in a chronological order. Not following this order of execution would probably lead to some additional issues.

1. Introduce CSS variables equivalents for all the LESS variables we use in the Flamingo skin (at least every single one from the color themes) – note that with the baseline 2024 for CSS @property, we could have typing on our CSS variables, and fallback values, which would IMO make the styles that much more robust. --> https://jira.xwiki.org/browse/XWIKI-22667
2. Start converting some .less script from our codebase to .css relying on those new variables. Note that from my experience, most LESS scripts are LESS and not CSS only because we needed some variables from the color themes. 1. provides an alternative for this and I’d expect the migration of most of those to be straightforward. This step will also be a good test to see what issues can arise when migrating from LESS to CSS. --> https://jira.xwiki.org/browse/XWIKI-22668
3. Deprecate the use of new LESS and LESS variables --> https://jira.xwiki.org/browse/XWIKI-22669
4. Propose either: a migrator app to convert all custom LESS SSX on the user instance OR a XWiki standard script that will propose to do this conversion to users when they update a LESS. (the best solution isn’t clear for me yet~) --> https://jira.xwiki.org/browse/XWIKI-22670
5. Migrate the public extensions to use only LESS
6. (Eventually, if we don’t come across code that CANNOT be migrated) Drop support for LESS in XWiki completely: most of it has already been converted to CSS at this point. --> https://jira.xwiki.org/browse/XWIKI-22671

Details on the implementation of each task

Task 1: Introduce CSS equivalents for all LESS variables

Historically, LESS variables have been introduced with the Flamingo Themes. Before that, XWiki relied on `Color Themes` that used velocity variables injected in CSS. For the sake of brevity, from now on we'll now call:

• Velocity Color Theme all the `oldcore` color themes with velocity variables
• Flamingo Theme or LESS Color Theme all the themes currently used based on variables defined in bootstrap3 using LESS.
• CSS Theme all the themes that support the set of CSS variables used by XWiki.

Our goal in this first task is to add the CSS Theme functionalities to all of the Flamingo themes.

In order to achieve this Task, I split the issue in different subtasks:

• Implement a Proof of Concept of a working CSS Theme using all of the variables exposed in the Flamingo theme editor.
• Showcase, discuss and improve this implementation of the CSS Theme on a forum topic
• List all of the bootstrap LESS variables used in the XWiki codebase.
  • XWiki-platform
  • Extensions
  • Ask for feedback by users?
• Extend the PoC to now support all of those variables that are not contained in the Flamingo Theme object.
• Validate the implementation
• Write tests to check the features

At the end of this step, I would expect the migration of most LESS files to be as simple as "replace the ##@## by ##--## and change the skinExtension / filename from LESS to CSS".

Some LESS variables are defined and used in a very specific context. It does not make sense to tackle them right now. In this step, we want to tackle all of the definitions of LESS variables at a global level. Note that to define CSS variables at a global level, one should include them in a ":root" ruleset.

From what I know, there's only a few places where XWiki defines LESS variables at a global level:

• variablesInit.vm (Flamingo theme variables, old themes, xwiki specific variables)
• variables.less (New variables provided by XWiki)
• lessCode from each colorTheme.
• variables.less from bootstrap
• type.less to overwrite default values from bootstrap.
• drawer.less with a set of XWiki specific drawer related variables
• edit.less (only a few variables, should be moved to variables.less...)
• headers.less (only a few variables, should be moved to variables.less...)
• layout.less (only a few variables, should be moved to variables.less...)
• tree.less from xwiki-tree-webjar

Here is a quick query on our codebase to find those LESS variable instanciations: https://github.com/search?q=repo%3Axwiki%2Fxwiki-platform+%2F%40.*%3A.*%3B%2F&type=code&p=1

Task 2: Migrate most of XWiki's LESS files to native CSS

See https://jira.xwiki.org/browse/XWIKI-22668 for a list

Done:

• 18.0.0rc1 finder.less -> finder.css

Task 3: Deprecate the use of new LESS and LESS variables

This will need a vote.

Task 4: Propose a tool to convert LESS files to CSS

Probably sharing the tool used for Task 2 with a nice UI

Task 5: Migrate the public extensions to use only LESS

NAN

Task 6: Drop support for LESS in XWiki

This will need a vote.