Page MenuHomePhabricator

[TECHNICAL GOAL] Split Vector into 2 separate skins with 2 different keys
Closed, ResolvedPublic


Specific: What do we want to achieve?

The skinversion system in Vector adds unnecessary friction in the following ways:

  • We have to add a skinversion field to any schema for any form of instrumentation to distinguish between the two experiences
  • There is a risk of fatals in production. We have to exercise caution in code, as constructing a Skin is supposed to be cheap, and cannot access session information e.g. user preferences in certain parts of the flow.
  • There is no way for extensions or user gadgets to ship different styles on the two Vectors. As a result, we are accumulating technical debt by shipping styles for two experiences together.
  • Certain behaviours of skins are tied. As a result we've had no choice but to make changes that impact legacy and modern Vector (for example wrapping menu items in span in legacy Vector)
  • It doesn't allow us to vary the parser cache. This impacts our planned changes to remove the table of contents from the parser output.

There are some benefits of the existing system that we want to keep:

  • Ability for user gadgets/styles/scripts to load in both experiences.

Measurable: How will we know when we've reached our goal?

There should be two skins in the user preferences for Vector. These should behave like any other skin e.g. MonoBook / Timeless

Achievable: What support will we need to achieve our goal?

The performance team have raised various concerns with a generic approach so we will take on technical debt to handle this.
We will likely need to coordinate with communities to make sure they are not disrupted by the change.

Relevant: Is this goal worthwhile?

This blocks table of contents feature, so yes. The skin version code is very domain-specific, and will likely cause confusion if we were to switch projects and come back to it, say a year later.

Separating the skins also allows us to retire/hide the legacy skin in the long-term future (although I don't think we've ever do this in practice), as well as allowing other teams to maintain ownership. More importantly it allows us to work on modern Vector without having concern for impacting the legacy experience which it is tied to.

This should lead to less CSS being shipped to both modern and legacy Vector (currently skinStyles is shared therefore many unnecessary styles are loaded on both experiences) e.g.

It should also reduce the potential of caching incidents. e.g.

It should also simplify instrumentation as all instrumentation can use the skin field rather than needing a custom skinversion field.

Time-bound: What is the time frame? Can we achieve this goal in the timeframe I've set?

Before the table of contents deployment.

More information

One of the goals of the desktop improvements project was to minimize disruption to end-users gadgets and site scripts and ensure that the new Vector is compatible with all existing gadgets. For this reason, we should split the skins into 2 different keys with shared wiki pages/gadgets

Phase 1 - Skin separation - Acceptance criteria

  • Vector will be broken into two internal skins that are hidden in user preferences. These will have skin keys vector and vector-2021
  • Vector will be the default skin. The Vector constructor, will make use of SkinFactory::getSkinOptions to work out which skins to apply
  • The skin key for Vector will be "vector"
  • No change to end user experience.

Phase 2 - Prepare and QA the skins - Acceptance criteria

  • All skinStyles that declare vector, will now declare vector and vector-2021. Currently this looks like it will be a manual job (see T288857)
  • Both of the new skins should load MediaWiki:Vector.css and MediaWiki:Vector.js. This is possible by using ResourceLoaderSiteModulePages and ResourceLoaderSiteStylesModulePages hooks.
  • A user script/stylesheet e.g User:Jdlrobson/Vector.css should apply to both skins.
  • The skins vector and vector-2021 will be made internal inside configuration using wgSkipSkins to prepare for deployment
  • The internal flag will be dropped inside Vector skin.json
  • We will undergo QA on both skins: ?useskin=vector and ?useskin=vector-2021 and ensure they are compatible with common gadgets and scripts.
  • Review the skin preference instrumentation with a QA engineer. Verify it gives us information we need and document any changes.
  • Review the skin preference version workflow with designer.

Phase 3 - Split the skins - Acceptance criteria

  • Once the train has rolled out we will update the configuration, changing the default skin to "vector" or "vector-2021" on desktop improvements projects. vector will be added to wgSkipSkins and vector and vector-2021 removed.
  • Provided everything has gone to plan, the "vector" key inside Vector's skin registration will be removed and removed from wgSkipSkins
  • Cleanup work will begin to remove skin version code and make the "both" skin legacy only

Related Objects

ResolvedBUG REPORTJdlrobson
ResolvedBUG REPORTJdlrobson
ResolvedBUG REPORTovasileva

Event Timeline

Jdlrobson renamed this task from Split Vector into 2 separate skins with 2 different keys to [EPIC] Split Vector into 2 separate skins with 2 different keys.Sep 15 2021, 5:00 PM

This is causing lots of problems in our day to day work and should be prioritized.

Change 713001 had a related patch set uploaded (by Jdlrobson; author: Jdlrobson):

[mediawiki/skins/Vector@master] Vector is split into 2 skins

@Jdlrobson just out of interest, why did you opt to have "skin versions" or "vector uses two internal skins", instead of just having a new vector21, make it default whenever you like, and drop "vector" whenever you like?

@Jdlrobson just out of interest, why did you opt to have "skin versions" or "vector uses two internal skins", instead of just having a new vector21, make it default whenever you like, and drop "vector" whenever you like?

A requirement of the project from the product department was to minimize disruption to users by ensuring that their gadgets and user scripts continued to work. A new skin would have required users to copy across all their gadgets.

A second benefit of this was that we are able to keep the two skins aligned as we refactored the code, which has made it more maintainable, however at this point when that work has been mostly done, there's little value in continuing to keep them tied to the same skin key. Hope this context is helpful.

Change 713001 merged by jenkins-bot:

[mediawiki/skins/Vector@master] Vector is split into 2 skins

I don't understand why legacy vector was renamed to "vector19" - why can't it just be "vector" as it has been for years? Just seems like unnecessary breakage for no gain. Renaming new/modern vector to something else makes perfect sense, though I'm not really a fan of "vector22" because it's going not make any sense in a few years and just be one of those things everyone has to learn. I feel like there are so many cool synonyms to Vector that would've made for a great new name (RIP Slate).

Vector was created in 2009 (became the default in 2010), so instead of vector19 it would have made more sense to call it vector2009.

Anyway, I agree with Legoktm that naming the new skin something else would have probably been clearer on most fronts.

There seems to be confusion on this thread about what we are doing, soo before that escalates I'm jumping away from the actual work to address this.
TDLR: There is no vector19. Renaming skin doesn't make technical sense at the current time as they share a lot of the same code and live in the same repo.

I don't understand why legacy vector was renamed to "vector19"

It's not going to be called vector19. The migration plan inside this ticket was a strawman proposal written in September and has since been changed as the requirements evolved.

After the team estimated it, and discussed it as a group, we found a way to make the migration without renaming existing Vector which we previously thought was impossible (T297756#7600222). FWIW we also decided that if we did rename it that vector-2010 would make more sense as a skin key.

Naming skins after year is something that Wordpress does with its themes, so that's where the idea came from.

Just seems like unnecessary breakage for no gain.

FWIW the gain would have been the ability to load CSS/JS on legacy Vector (MediaWiki:Vector-2010.css) without loading it also load on the new Vector skin (MediaWiki:Vector-2022.css) . Currently, both skins have to load MediaWiki:Vector.css for backwards compatibility.

feel like there are so many cool synonyms to Vector that would've made for a great new name

Note, while we're splitting the skins, they will continue to live inside the Vector skin repository, as about 50% of the code is shared between the two skins. The two skins also share behaviors e.g. gadgets that work on old Vector are expected to work on modern Vector and MediaWiki:Vector.css is currently loaded on both skins. French Wikipedia has the new skin as default so we have to be super careful about breaking any of their on-wiki gadgets. Pairing the skins allows us to share maintenance, and keep the old Vector updated with latest best practices.

This might change in the future. We've renamed skins before. (Example: Minerva) and the team has talked about when it might make sense to use two separate repositories for the skins from a technical point of view, but it does come at a cost, so for now, at least from a technical perspective, it makes sense for the skin to have Vector in its name.

NOTE: See also T234907 for the RFC relating to the decision to consider the new skin an iteration of Vector. Reconsidering the name is out of scope for this technical task which simply preserves the status quo.

Hello! A kind, gentle, but desperate reminder to please keep gadget and user script maintainers up-to-date by announcing these sort of changes through Tech News! I assume the intention was a mostly seamless rollout to users, but of course scripts/gadgets are going to break or become unavailable when we've effectively introduced a new skin (vector-yyyy vs vector). Pweez try to remember moving forward 🙏 I did not know until today that we were splitting old/legacy Vector into different skins, much less that there are apparently three versions in production right now.

That said I think the skin split is a good idea, and I am extremely excited for the features Vector 202X will bring! :)

EDIT: I see now from T300757 that the skin split (or at least the new return value for mw.config.get('skin')) wasn't intended to go out this quickly, hence you didn't have the chance to utilize Tech News even if you wanted to... Allow me to apologize if I came off too strong, while also still stressing the importance of Tech News, in the event that wasn't on the to-dos (I don't see User-notice on here or the subtasks). Thanks and warm regards :)

Jdlrobson renamed this task from [EPIC] Split Vector into 2 separate skins with 2 different keys to [TECHNICAL GOAL] Split Vector into 2 separate skins with 2 different keys.Feb 16 2022, 10:23 PM