Page MenuHomePhabricator

RFC: Skin templating
Open, Needs TriagePublic

Description

This RFC aims to revamp how skins are created, to improve usability in creating skins, extending skins with new UI (in Extensions), and giving more power and flexibility for system administrators to customise skins for their own sites without causing undue burden on upgrades.

Link to RFC on mediawiki.org

Event Timeline

Skizzerz created this task.Feb 26 2019, 5:43 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 26 2019, 5:43 PM
Isarra added a subscriber: Isarra.Feb 26 2019, 5:55 PM
Skizzerz updated the task description. (Show Details)Feb 26 2019, 5:59 PM
nray added a subscriber: nray.Feb 26 2019, 6:47 PM
brion added a subscriber: brion.Feb 28 2019, 6:42 AM

Unless anyone has any lingering concerns or questions they'd like addressed before the RFC is submitted for TechCom perusal, I'm going to be moving this RFC along to the next step of the process in a few days (requesting an IRC meeting).

kchapman moved this task from Inbox to Under discussion on the TechCom-RFC board.Mar 6 2019, 10:22 PM

To be honest I'm still very confused about this RFC. We had an RFC about using templates in MediaWiki across client and server and settled on Mustache for better or worse in Requests_for_comment/HTML_templating_library.

it was resolved that Mustache be used as the recommended template processor in core and extensions, for both JavaScript and PHP code.

The proposal in Skin templating seems identical to the one MinervaNeue has been using happily for many years and I'd support it. I don't understand what our hopes are for having an RFC discussion about this and I have little to add apart from JDI!

Skizzerz added a comment.EditedMar 12 2019, 10:47 PM

This RFC aims to deprecate BaseTemplate and as such make backwards-incompatible changes to the entire skinning system as a whole. This does not open up the option of using Mustache to generate parts of skins with PHP code to glue those parts together, it makes using Mustache mandatory for skins and eliminates PHP from the presentation logic entirely.

This RFC is not about picking the template library, that work is already complete. This RFC is about dragging our skinning system into the 21st century without legacy baggage or compromises on vision.

All skins (WMF-deployed and 3rd party) would need to be modified to conform to this new scheme. No existing skin, not even MinervaNeue, is currently compatible. That being said, MinervaNeue serves as a good example of the direction I want to take with this RFC, with its multiple hierarchical mustache templates.

Given the scope of changes, an RFC is necessary. The RFC page states "The Wikimedia RFC Process is used to track technical decisions and more complex changes that are strategic, cross-cutting, and/or hard to undo."

Strategic? Yes, this proposal aims to rip out and re-write the current skinning system with something that is sane and maintainable
Cross-cutting? Yes, this proposal impacts every skin, both WMF and 3rd party. No existing skin will be compatible with the new system without modification
Hard to undo? Not as much, we can always just roll back the change. New skins made with the new system would need some sort of shim to work, but could otherwise (mostly) function with the old BaseTemplate.

That said, I think the proposal is ready for an IRC meeting to finish discussing it. There are still some unresolved things such as how to handle caching of skins, which I can't entirely qualify by myself.

Izno added a subscriber: Izno.Mar 12 2019, 11:36 PM
tstarling added a subscriber: tstarling.

That said, I think the proposal is ready for an IRC meeting to finish discussing it. There are still some unresolved things such as how to handle caching of skins, which I can't entirely qualify by myself.

Moving on the RFC workboard accordingly.

This RFC aims to deprecate BaseTemplate and as such make backwards-incompatible changes to the entire skinning system as a whole.

Thanks for this clarification! FWIW any skin could copy BaseTemplate into their repo and/or we could leave it registered but deprecated and unused for several releases if need be. I do think templates serve a better purpose than this PHP class. Thanks for your patience with me!

daniel added a subscriber: daniel.Mar 14 2019, 7:08 AM

@Skizzerz TechCom is trying to shift weight from IRC meetings to discussion here on phabricator. For this purpose, I suggest to copy the essential parts of the RFC from the wiki to the task description and writing an email to wikitech-l, asking for input. This would mean moving the RFC to "under discussion" on the RFC board for now. If it appears like there is consensus forming in the discussion on this ticket, we could perhaps move the RFC directly to last call without the need for an IRC meeting (or you could request an IRC meeting again, if you think it would be useful).

Thanks for this clarification! FWIW any skin could copy BaseTemplate into their repo and/or we could leave it registered but deprecated and unused for several releases if need be. I do think templates serve a better purpose than this PHP class. Thanks for your patience with me!

The current plan is to leave BaseTemplate in-place, but deprecated and unused by core, for at least 3-4 releases before it is removed. This gives 3rd parties ample time to re-work their skins which use BaseTemplate to use the new system instead. Depending on feedback from 3rd parties, that may or may not be extended. I'm hoping to provide good documentation for how to do things under the new system (once built) to ease the process for the 3rd parties, in addition to doing work to convert WMF-deployed skins as well as a couple of 3rd party skins in Gerrit (which can be used as examples).

@Skizzerz TechCom is trying to shift weight from IRC meetings to discussion here on phabricator. For this purpose, I suggest to copy the essential parts of the RFC from the wiki to the task description and writing an email to wikitech-l, asking for input. This would mean moving the RFC to "under discussion" on the RFC board for now. If it appears like there is consensus forming in the discussion on this ticket, we could perhaps move the RFC directly to last call without the need for an IRC meeting (or you could request an IRC meeting again, if you think it would be useful).

A wikitech-l thread for this RFC was sent on February 27, https://lists.wikimedia.org/pipermail/wikitech-l/2019-February/091594.html

No responses were made to that thread. If needed, I could bump it to add a last call for input and point at this thread. I wanted to avoid duplicating info between the ticket and the wiki, as edits to one won't necessarily be reflected in the other source.

I could perhaps work on some components of the RFC as a proof-of-concept, but I don't want to put too much effort into development which would possibly be thrown away in case this discussion leads to a change in direction.

An elephant in the room is what will be happening to the DOM as a result of this RFC. As one of the explicit goals of this RFC is to unify DOM across skins so that Gadget authors don't have to do skin-specific things if they don't have to. This means, however, that the overall DOM of most if not all skins will change in order to make them unified.

I was thinking about using Vector as the base DOM to adhere everything to, which would reduce the work needed to convert Gadgets and the like, but Vector's DOM can be charitably described as "not very flexible".

What are everyone's thoughts on how to address making a consistent DOM across all skins? In addition to the development effort involved, an outreach effort will almost certainly be required. In addition, deployment considerations need to be made. How do we get a smooth rollout of the changes in a way that doesn't just break everything?

What are everyone's thoughts on how to address making a consistent DOM across all skins?

If all skins are to share the same DOM structure, why have templating at all? If the DOM output is the same, the templates would be the same, no? In that case, skins would just consist of CSS...

It seems to me like these questions should be decoupled. 1) should we move the skin system to use (mustache) templates? And 2) should all skins share the same DOM strcucture (i.e. become styles)? And if not, what parts of the DOM structure should be the same for all skins?

Why does the DOM need to be consistent? It certainly isn't in Minerva. I would truly value having a proper API for accessing skins via gadgets rather than relying on CSS selectors.

I would truly value having a proper API for accessing skins via gadgets rather than relying on CSS selectors.

+1, though that's probably yet another RFC, and quite a bit of work...

Why does the DOM need to be consistent? It certainly isn't in Minerva. I would truly value having a proper API for accessing skins via gadgets rather than relying on CSS selectors.

Doesn't have to be! The goal listed is so that Gadgets can work well across skins without needing to resort to skin-specific hacks. A (mostly) consistent DOM is one way to achieve this, but is not the only way, as you've noted.

When I say "consistent DOM", I mean things like "use the same IDs / class names across skins where it makes sense to do so". So, the content container id will always be mainContent, content actions will always be p-cactions, and the like. Skins will almost certainly need to vary how they order things and lay things out by necessity in order to achieve whatever makes that skin work.

As an easy example, one skin may feature a left sidebar and content area, whereas another skin may have both a left and right sidebar area. These will by necessity have different elements composing that, and therefore a different overall DOM. I'm trying to address issues where a Gadget tries to work with both skins, say, to add something to the search bar. The search bar happens to be located in the left sidebar on skin 1, and the right sidebar on skin 2. It shouldn't have to jump through hoops to get to the search bar in each skin; they should use the same id or whatnot so the Gadget can directly drill to it in a skin-agnostic fashion. An API would serve this purpose as well, and would likely be a better way of going about it.

I think at this point I do need to work on an example just to get the idea across better and give people something concrete to look at in order to get an idea of the scope of changes I'm proposing here and what benefits those changes could have. I hope to have that ready in a week or so. In the meantime, please continue to comment on anything you notice :)

Consistent CSS classes and element IDs would indeed be great. This could go along with documentation stating explicitly what guarantees are (not) given.

I feel this RFC is focussing too much in a specific outcome, as such it is lacking a cohesive problem statement. This is, in my opinion, making it difficult for others to participate in a productive way.

There are a number of perceived problems presented in this RFC currently that I think do not have wide agreement, and as such would be very difficult to make progress on.

  • Why should a gadget be able to inspect the DOM equally and find no differences between skins? What is the end-user problem this is aiming to achieve? I feel that alone could be its own RFC.
  • Why should all skins use Mustache? It sounds like this is proposing that skins have no control over the HTML output. If that is so, then what would they be able to do with Mustache? If they are allowed to change the HTML output, why not allow them to continue to use BaseTemplate if they so desire?

I am all for consistency, but I am also a big supporter of boundaries between different components. I feel that MediaWiki core caring about how a skin produces its output crosses a boundary that shouldn't be crossed.

We can certainly impose conventions on what is found in the output. And if we want to codify that and make it impossible to breach, that's an interesting idea. But that leads me back to the question: If skins have no control over the output, what would they be using Mustache for?

I believe that the user stories mentioned in Goals adequately describe what this RFC is meant to tackle. If you disagree with some of the user stories, that is a valuable discussion to have. Many of these stories are things I have heard from other people across various channels. The "consistent DOM" point arose around VisualEditor rather than Gadgets, as VE expects certain elements to exist in order to power the editor interface. I mentioned Gadgets in the RFC to generalize it more as any js which would want to add things to a page needs to know where it should be adding it.

You are correct in that the RFC proposes an implementation in addition to saying "here is a problem, let's discuss it." This is because the problem is general and wide-reaching, and the proposed implementation has been done before to great success in other software. There are almost certainly problems with the proposal, however, and I am hoping that is what the RFC process will expose. If the end result becomes "the implementation proposed does not adequately solve the problems it needs to solve," then that discussion will be invaluable for tweaking and coming up with something that does work.

Why should a gadget be able to inspect the DOM equally and find no differences between skins? What is the end-user problem this is aiming to achieve? I feel that alone could be its own RFC.

I am not advocating that the DOM be exactly the same across every skin. Indeed, I don't believe that is even possible to achieve. Instead, certain key elements should be as consistent as possible between them so that things written for one skin will ideally work with others as well, if they all do things (mostly) similarly. In other words, I hope to establish a convention and get skins to mostly stick to it.

Should this go through, Core will be moving parts of its own HTML generation into templates, such as the sidebar and table of contents. I aim to also ship a base set of templates (to provide the mostly-consistent DOM mentioned above) as part of "Fallback." Skins can override as many or as few of these templates as they want in order to tweak things how they want them to be. This is an improvement over the status quo where a skin currently must override everything, even if it only wants to make 2 or 3 small tweaks.

Why should all skins use Mustache? It sounds like this is proposing that skins have no control over the HTML output. If that is so, then what would they be able to do with Mustache? If they are allowed to change the HTML output, why not allow them to continue to use BaseTemplate if they so desire?

We ship a set of base templates. Skins override as many or as few of these templates as they want in order to customize their generated HTML in a skin-specific way. The skin has complete control over the HTML output, even more than it currently does (for example, control over how the Table of Contents HTML is generated).

We can certainly impose conventions on what is found in the output. And if we want to codify that and make it impossible to breach, that's an interesting idea. But that leads me back to the question: If skins have no control over the output, what would they be using Mustache for?

It will not be impossible to breach the conventions. The conventions are shipped as part of the Fallback skin to provide new skins an easy base to start building from, but the expectation is that they will deviate from at least some templates to do their thing. However, by only overriding the bits they need to override, everything else remains the same and we achieve a higher level of cohesion between skins for their DOM.

Can you please let me know what lead you to believe that core would be stringently enforcing the rendered HTML, and preventing skins from doing their own thing? I would like to revise those sections of the RFC to make it more clear what the intent is. Alternatively, please feel free to edit it yourself, it's a wiki after all :)

kchapman added a subscriber: kchapman.EditedMar 22 2019, 8:00 PM

TechCom is hosting an IRC meeting on this topic on March 27 at 11pm PST (March 28 06:00 UTC, 07:00 CET) in #wikimedia-office

Cancelled to be reschedule during the other IRC window at a later date

@kchapman Would it be possible to do this meeting at some other time/day? As one of the people most familiar with the current skinning system, it'd probably be good if I could make it, and that is not a time I will be able to make as I am going to be on a plane somewhere over the atlantic.

@Isarra we are going to reschedule.

TechCom is hosting an IRC meeting on April 3rd at 2pm PST (22:00 UTC, 23:00 CET) in #wikimedia-office

Action items from the IRC discussion:

*<Skizzerz> 1. Expand upon the RFC to include a migration plan
*<Skizzerz> 2. Add a section for possible future expansion