Page MenuHomePhabricator

[EPIC] <Core Technology> Upgrade MediaWiki projects from Vue 2 to Vue 3
Open, Stalled, HighPublic

Description

Upgrade MediaWiki projects to Vue 3 and remove compatibility build

Current Status (5/31/23)
  • MediaWiki currently ships Vue 3 with the Compatibility build included.
  • New Vue-based features and Codex components are all being developed against the full Vue 3 API. However, there are still some legacy Vue apps embedded in skins or extensions which rely on Vue 2 behavior.
Acceptance Criteria
  • All code that uses Vue has been migrated to the full version of Vue 3, and the compatibility build has been removed.
  • This work must be completed before Vue 2 reaches EOL at the end of 2023.
Next Steps:
  • Now that we are using Vue 3 with the Compatibility Build across MediaWiki, we should go into each codebase which is using Vue.js and follow the steps documented in the Vue 3 Migration Guide. To test Vue 3 compatibility, set compatConfig: { MODE: 3 } as an option in each component file – this disables all compatibility mode features and forces full Vue 3 behavior on a per-component basis. See T289020: Migrate all extension/skin code to Vue 3 for a list of all Vue-based features; subtasks should be filed against that task for each codebase, and patches should be written against the respective codebase-specific tasks to add compatConfig flags to Vue components. These patches can be tested, deployed, and (if necessary) reverted normally.
Steps: Vue 3 Full Build
  • Begin migrating all code using Vue, addressing migration warnings then disabling compat mode for migrated components (T289020)
  • Ensure all code using Vuex is ready to be migrated (T289089)
  • Wait for the security readiness review for Vuex 4 (T288768) to be completed
  • Upgrade the Vuex version in MediaWiki to 4.0.2 (T289102)
  • Migrate code using Vuex to the new calling style (T289103)
  • Once everything is migrated, remove compatibility code and switch from the migration build of Vue to the regular build (T289104)
  • Clean up other compatibility/migration remnants, like the { compatConfig: { MODE: 3 } } settings disabling compat mode for migrated components (T289105)
Deploy Checklist
  • Coordinate QA timelines and QA sign-off across teams (product/program)
  • Target deploy train and post ETA in comments
  • Prod verify and address fast-follows

Details

ReferenceSource BranchDest BranchAuthorTitle
repos/design-systems/CodexExample!9remove-vue-compatmainegardnerRemove Vue.configureCompat call
Customize query in GitLab

Related Objects

StatusSubtypeAssignedTask
Duplicate STH
Stalledegardner
Resolvedsbassett
ResolvedMstyles
ResolvedCatrope
ResolvedNone
Resolvedegardner
ResolvedLucas_Werkmeister_WMDE
ResolvedMichael
ResolvedLucas_Werkmeister_WMDE
ResolvedLucas_Werkmeister_WMDE
OpenNone
ResolvedLucas_Werkmeister_WMDE
OpenNone
ResolvedCatrope
ResolvedCatrope
ResolvedSimoneThisDot
ResolvedCatrope
ResolvedCatrope
ResolvedCatrope
ResolvedJdforrester-WMF
DeclinedNone
ResolvedCatrope
Resolvedegardner
ResolvedSimoneThisDot
ResolvedNone
ResolvedMichael
ResolvedMichael
ResolvedMichael
ResolvedMichael
ResolvedLucas_Werkmeister_WMDE
ResolvedLucas_Werkmeister_WMDE
ResolvedLucas_Werkmeister_WMDE
ResolvedMichael
ResolvedMichael
ResolvedMichael
ResolvedSimoneThisDot
Resolvedegardner
Resolvedegardner
Resolvedegardner
Resolvedegardner
Resolvedngkountas
ResolvedSgs
ResolvedUrbanecm_WMF
DeclinedNone
ResolvedCatrope
ResolvedCatrope
ResolvedCatrope
ResolvedSBisson
ResolvedCatrope
ResolvedCatrope
ResolvedCatrope
ResolvedNone
Resolvedegardner
Resolvedegardner
Openegardner
ResolvedJdforrester-WMF
Resolvedegardner
ResolvedEdtadros
ResolvedSimoneThisDot
StalledNone
ResolvedJdforrester-WMF
ResolvedCatrope
ResolvedSimoneThisDot
Resolved AdesojiThisDot
ResolvedSimoneThisDot
ResolvedSimoneThisDot
ResolvedSimoneThisDot
ResolvedSimoneThisDot
ResolvedSimoneThisDot
ResolvedSimoneThisDot
ResolvedJdlrobson
ResolvedJdlrobson
ResolvedJdlrobson
InvalidNone
Resolvedegardner
DeclinedNone
ResolvedVolker_E
ResolvedNone
ResolvedNone
ResolvedCatrope
OpenBUG REPORTNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

Hey @Catrope, if you were starting a new MW extension using Vuejs in the next week or two, would you

  1. use Vue 2 and migrate it to Vue 3 later or
  2. start with Vue 3 by including a private copy and use the official version later or
  3. something else

The extension won't be deployed anywhere for several months. The whole team is new to Vue so it would feel wasteful to learn a style and quickly migrate to a different style (of there are significant differences between v2 and v3, that it).

thanks!

Hey @Catrope, if you were starting a new MW extension using Vuejs in the next week or two, would you

  1. use Vue 2 and migrate it to Vue 3 later or
  2. start with Vue 3 by including a private copy and use the official version later or
  3. something else

Apologies for the late response, I started my vacation the day after you posted your comment.

I will ask the other engineers on the Design Systems Team to weigh in too (cc @egardner , @AnneT), but my recommendation would be #1. Use the Vue copy in MW core, and upgrade along with it.

The extension won't be deployed anywhere for several months. The whole team is new to Vue so it would feel wasteful to learn a style and quickly migrate to a different style (of there are significant differences between v2 and v3, that it).

The biggest difference between v2 and v3 that affects how you write code and how you think about things is the composition API, but we have already installed a plugin for v2 that provides that API, and some of our existing code written for v2 already uses it. The remaining differences between v2 and v3 are relatively minor. There are some other nice features that v3 adds, and there are some breaking changes that make upgrading harder (most which are papered over by Vue's migration build), but they're mostly things that you wouldn't encounter very often and that don't affect the way that you would architect or think about things. An example that I think is pretty representative is that the behavior of <div :some-attribute="foo"> changed in the case where foo is false (from dropping the attribute to setting it to the string "false"). For a list of new features and breaking changes see this page in the migration guide.

Overall, most code written for Vue 2 (especially user interface code that is just programming an application rather than providing a library) works in Vue 3 with minor modifications, and works with the compat build of Vue 3 with no or minimal modifications in most cases; see T289019 for our adventures in validating this and finding edge cases. In some cases you may write something differently for Vue 2 than you would for Vue 3, but I think those cases are pretty limited and specialized; the ones I can think of are the teleport feature and the ability to use Vue-native two-way bindings (v-model) for multiple props in the same component. If you start your project with Vue 2 and then keep a running list of things you'll make nicer once you have Vue 3, I think that list will not be empty but will be fairly short.

We're hoping to upgrade to Vue 3 (with compatibility) in MW core soon, so hopefully this issue will be moot anyway. The main blockers are the security review (T257734) which is estimated to be completed by the end of September, and unbreaking the extension breakages in T289019. If that goes well we could have Vue 3 available in 3-4 weeks, but we haven't tried running it against Wikidata yet, so we'll see.

I agree that Vue 2 is safest for now, and that migration to Vue 3 shouldn't be very time-consuming or difficult, especially with the compatibility build.

To expand a bit on the Composition API: Vue 2 components use the Options API, which is still available in Vue 3, but you can also start using Vue 3' Composition API via the Composition API plugin. You can check out how we're using it in a few WVUI components (Checkbox, Dropdown, and Radio - all the others exclusively use the Options API).

When starting out with Vue I found the Options API to be very straightforward to learn, so if you want to keep your first Vue project simple you could stick with it. However, the Composition API offers some benefits (better code organization and sharing, for example) and you'll also get a chance to learn Vue 3's new reactivity system, which offers more granular control of reactivity than the previous version.

STH changed the task status from Open to In Progress.Dec 23 2021, 7:39 PM
STH triaged this task as High priority.

Adding Design-Systems-Team because Design-Systems-team-20200324-20220422 got archived though this open task has no other active project tags associated, so it cannot be found on boards.

STH changed the task status from In Progress to Stalled.Apr 30 2022, 5:37 PM

Teams such as WMDE have requested advance notice to plan this in to an upcoming quarter. We can target the July-September quarter to complete this and should begin outreach to affected teams in May/June.

STH lowered the priority of this task from High to Medium.May 1 2022, 1:20 PM
STH renamed this task from [Epic] Migrate from Vue 2 to Vue 3 to <Core Technology> Upgrade MediaWiki projects from Vue 2 to Vue 3.May 20 2022, 2:47 PM
STH updated the task description. (Show Details)
ldelench_wmf renamed this task from <Core Technology> Upgrade MediaWiki projects from Vue 2 to Vue 3 to [EPIC] <Core Technology> Upgrade MediaWiki projects from Vue 2 to Vue 3.Nov 17 2022, 11:25 PM
Restricted Application raised the priority of this task from Medium to High. · View Herald TranscriptMay 31 2023, 6:35 PM

This task is in progress again, but we can consider it "blocked" until T289020: Migrate all extension/skin code to Vue 3 is complete.

I did a quick search for Vue.configureCompat calls across our codebases. Unlike some of the other compat code artifacts, this line will cause JS to error out once we remove the migration build, since that method will no longer exist on the Vue object. We will need to ensure all traces of this are removed from any code that is still in production before we flip the switch.

Here are the places that still include this code as of Tuesday Nov 28:

  • The Extension:VueTest (this is a legacy example repo maintained by DST; we've talked about replacing this with the more modern CodexExample; perhaps it's time to archive this repo?) – this is not deployed in production anywhere
  • Extension:MachineVision – this has also been officially un-deployed, right?
  • Extension:FileImporter – who maintains this?
  • CodexExample Extension – this lives in GitLab and is not picked up by CodeSearch. I will update this shortly.

All of these configureCompat calls have already been wrapped in if statements, so they should be safe. See e.g. https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VueTest/+/968789 . We should remove these after the migration is complete, but for now I think it makes the most sense to keep them as conditional calls.