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
      • Done before the waves
      • Wave A: trivial
      • Wave B: vars only
      • Wave C: mixins
      • Wave D: heavy
      • Wave E: last
      • Not triaged yet
    • 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

Tracked in XWIKI-22668. The tables below show the live status of each issue in JIRA.

The remaining LESS files are converted in the order below, to make the progress easier to follow. The files are grouped in waves of increasing difficulty, and at most 5 conversion PRs are kept open at once so that reviews don't pile up.

Done before the waves

Wave A: trivial

Plain rules and simple variables, or dead code that can be removed.

Wave B: vars only

Uses LESS variables that need a CSS custom property counterpart.

Wave C: mixins

Calls LESS mixins that have to be inlined or replaced.

Wave D: heavy

Large files that rely heavily on LESS features.

Wave E: last

Depends on the other waves being done. XWIKI-23651 covers 26 LESS SSX pages, split by module.

Not triaged yet

These skin files have no issue yet, and may stay out of scope for now:

• action-menus.less: large file with many color functions.
• buttons.less: many Bootstrap mixin calls and color functions.
• livetable.less: the Livetable is being replaced by Live Data.

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.