NOTE: This RFC is a draft but please feel free to contribute thoughts to help me articulate my own! Please also let me know if I can clarify anything!
NOTE: Although I'm associated with WMF this is likely to be a personal project if accepted done during volunteer time.
* Affected components: Skin, TemplateParser, Selected(and stable) skins: Modern/CologneBlue/Monobook, potentially API
* Engineer(s) or team for initial implementation: (Ideally) Core Platform + Web
* Code steward: TBD
# Motivation
There is dissatisfaction with the existing skin system. I recently documented this in a blog post [[ https://phabricator.wikimedia.org/phame/post/view/188/why_does_building_a_skin_require_php_knowledge/ | Why does building a skin require PHP knowledge? ]]
As far as I can see the main issues being:
* It’s difficult to create a new skin unless you have a wide range of skills including knowledge of PHP and backend technologies as well as mediawiki internals
* Deploying an existing skin into production adds a huge maintenance burden given the lack of boundaries to the skin system
* It is difficult to integrate extensions with existing skins which do not share a common markup or API for key interface elements.
* We have a few 'official' and modern looking skins released in the tarballs and very few skin developers
* Most mediawiki instances are using the Vector skin and sharing look and feel with other sites because of the above reasons
## Who am I?
I have 8 years of experience of writing skins for MediaWiki full time. I built the Minerva skin and am now working on the desktop refresh. I’ve hit many of the issues with the existing skin “architecture” and exploited the lack of boundaries in the development of Minerva.
Having grown up in the Myspace and Tumblr generation, I’ve seen first hand at what is possible when you lower the barrier for entry for would-be developers. My theory is that by removing the need to know PHP we will open ourselves up to a larger audience of skin developers.
TODO: Add data around skillset availability for PHP+CSS+JS vs CSS+JS.
# Requirements
## specification
* It should be possible to create a skin using only the JSON, CSS (or LESS), Mustache (HTML) technologies.
A skin can optionally use JS and PHP if necessary.
* Flexible template data that is subject to a strict and stable skin API is sent to the Mustache template. This template data will use a PHP unit test to enforce the following rules:
** Any HTML will be prefixed with `html-`
** Any data will be prefixed with `data-` (associative array) or `array-` (if flat array)
** The template data will be subject to the deprecation policy.
** Mustache/TemplateParser will emit warnings if template keys that don't exist are used (see T128864)
** Template keys that are deprecated will emit deprecation warnings using the solution for T128864
* It should be possible for a skin to be declared as being a modern Mustache skin without extending a PHP class
* A skin declared as a Mustache skin will automatically have a stylesheet associated with it that is provided by the ResourceLoader module `skins.<skinkey>". If none is defined then the skin will appear unstyled.
* A Mustache skin will automatically add a ResourceLoader module `skins.<skinkey>.scripts" as its JavaScript entry point. If none is defined the skin will be assumed to have no JavaScript code
* A skin declared as a Mustache skin must declare a template inside a `templates/` folder matching the lowercase version of its skin name. * If no template is found a RuntimeException will occur.
* A skin may use template partials if wanted. They can use arbitary names.
* Skins using the Mustache render will no longer be able to declare their own hooks other than those provided by core. This will keep the skin API scoped.
## To be decided
It's not clear to me whether the new MustacheTemplate should inherit from QuickTemplate or to start a new class duplicating and refactoring code where necessary.
## Goals
* We will implement a Mustache based skin architecture that matches the specification
* The new skin API is documented and stable.
* We will rewrite Modern, Cologne Blue and Monobook in the new system to simplify their code using the new skin API.
* The ExampleSkin is deprecated and updated to point to a skin generator based on http://skinomatic.wmflabs.org/ which will generate frontend only scaffolding for a skin with updated best practices.
# Exploration
Once a specification is agreed upon, I hope to make use of [[ https://www.mediawiki.org/wiki/Core_Platform_Team/CPT_Work_Processes/Taking_part_in_Clinic_Duty | Core Platform Team Clinic Duty ]]
## Proof of concept:
The following two patches should hopefully capture the vision here
* [[ https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/584068/ | A modern and restrictive skin system using Mustache ]]
* Modern: [[ https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Modern/+/585834/ | Make Modern modern again (at least from a technology standpoint) ]]
The fully functional [[ http://skinomatic.wmflabs.org/ | Skinomatic tool ]] should hopefully showcase the power of utilizing the underlying technologies (be sure to click build button in top right and try the resulting zip file in your MediaWiki instance!