WMF's insufficient documentation and communication seems to also confuse contributors: https://www.mediawiki.org/wiki/Topic:Wp7kzldzuigdbsbg

8 months ago this was announced on https://lists.wikimedia.org/hyperkitty/list/wikitech-l@lists.wikimedia.org/message/SOZREBYR36PUNFZXMIUBVAIOQI4N7PDU/ so I just took the liberty to update https://www.mediawiki.org/w/index.php?title=Design&type=revision&diff=5162939&oldid=4927122

It would be lovely if the WMF could also put efforts into updating its docs in many various places (on-wiki, Phab project tag descriptions, etc) so volunteers don't waste time creating code using outdated implementations.

@STHart: How could this task get some attention?

Thanks @Aklapper, I can see how this conflicting information is confusing. Vue.js is being used on a team-by-team basis, and while I am not familiar with the status of OOUI projects, I can help clarify the big-picture work around Vue.js. I also want to mention that the Design Systems Team is going through an overhaul of our processes and documentation, so there may be some changes in how these tasks are structured on our Phabricator boards soon (hopefully, with a much clearer status and priority indicator).

To summarize where things stand: WMF collectively agreed to move towards Vue.js after the developer summit, and a few teams were able to use Vue right away, but the "how and when" is something that should be made on a team-by-team basis and depends on a number of factors like their roadmaps and opportunities to implement. The Design Systems Team is working with teams to adopt Vue as soon as it becomes a feasible option for them. While connecting with teams since the summit, a few long-standing infrastructure debts surfaced as blockers for adopting Vue on MediaWiki at full-scale. In some cases, use of Vue is limited to upgrading/replacing Vue code that already exists (e.g. WVUI) for performance and rendering concerns that we are investigating in T289208: Develop and document a proposal for when to use Vue/Codex. There is no timeline for this work yet, since we're figuring out the scope and impact, but it will likely move into a TDMP in the upcoming weeks.

Since many teams are using Vue.js in different ways, and will adopt Vue.js at unknown times, I think we need to reframe Vue.js work as an agreed-upon shift in practices with the Design Systems Team leading the path forward to unblock adoption and lower the barrier to entry to frontend development across the board. We are continuing to work on Codex, because even though it is linked to Vue as far as adoption blockers go, there are several teams who can use and benefit from it right now. Currently, we in our testing/prototype phase: T299138: [Milestone] Codex Alpha: First Release and aim to replace WVUI with Codex in May 2022 T302025: Upgrade Codex to Beta version. The high-level Codex roadmap is on our MediaWiki page.

As far as Vue goes, next steps are captured in T289017: [EPIC] <Core Technology> Upgrade MediaWiki projects from Vue 2 to Vue 3 and scope is limited to projects/teams who are already using Vue.js. I hope this information is useful for now! I will discuss this during our team's planning session this week to make sure I haven't missed anything, and will file a task to update documentation and circulate.

I think this task is a good candidate for prioritization during the team's next sprint. There are a lot of recent developments and recommendations that could probably be tied together in one place and communicated more widely:

• All currently-in-production features which had relied on WVUI have now been migrated to Codex (QuickSurveys, TypeaheadSearch)
• Codex has been made available in MediaWiki but is still very much in "alpha"; not necessarily suitable for all projects yet
• MW has upgraded to Vue 3 everywhere, but we are still using the compatibility build. All new Vue code should target Vue 3 and existing code should start addressing compatibility issues so we can remove the migration build; DST will provide guidelines for this shortly (T313358)
• Similarly we should make sure our guidelines for writing Vue code, unit tests, etc are up to date
• What is the central "source of truth" for info around Vue, Codex, new front-end standards, etc? Should we point people to the DST MediaWiki page?
• Research into getting SSR working is happening now; it will be a while before this is production ready but we are working on it (T286963)

A lot of documentation on these topics already exists; we just need to update and centralize things.

Totally agree @egardner ; would you be open to pairing on this for a bit next week?

As part of this task, I would suggest not only consolidating and updating documentation, but establishing owners of documentation and creating processes for keeping it updated (e.g. what needs to be updating monthly? Quarterly? Per release? etc...) Happy to help with this too!

Related: T306115/T297315

Proposal: I'd like to create a current status sub-page beneath the Design Systems Team page on MediaWiki.

For discoverability, that page can be transcluded into the top-level team page (as well as anywhere else that needs to reference it).

I went ahead and added a draft page as a placeholder; I can flesh it out this week.

Also, we have a lot of other sub-pages that are either historical or totally obsolete. I've added the {{historical}} banner where applicable, but I wonder if we want to actually move things into an archive sub-directory? Currently all of these old pages still show up in the "all subpages" section of the team page, potentially creating some confusion.

@egardner wrote:

• Archive, delete, or prune old Vue Migration Team pages as necessary (may need help from someone with admin privileges to delete pages).

Why would you delete the old wikipages? They show the historical state and how we got to where we are, and will be of interest to not just researchers but interested contributors looking for the history. Better would be to update them so that they read kinda like a Wikipedia article about that historical thing ("Foo was a dingus for flubbering the bar. It was developed and maintained by the [[Barbaz Team of Greatness]] … In 2022 it was replaced by AcmeWidget™ maintained by [[Team HotShots]].")

Ok, since the Vue.js decision announcement I've been looking for some kind of status or guidance or roadmap for client-side UI for Gadget and User script developers. That used to be jQuery UI, but upstream put that in maintenance-only mode in 2018 and it was deprecated in MW 1.29. The new hotness was OOUI, but it was never very suitable for this use case and realistically now will never be. Where the puck is going is, from all appearances, Codex; but try as I might I can't find more than incidental mentions of User scripts and Gadgets as a use case (and mostly in the "select a framework" Phab task). There's all of one open task on the Codex workboard (T311099) related to this, and that's just the icons.

So, in the interest of not wasting yet more volunteer time on a dead end, it'd be helpful to get at least basic documentation for this use case up and integrated somewhere. Express it in the scope, document the current status, and have some kind of roadmap (that should probably end with "jQuery UI removed from WMF wikis"). Bonus points for something more use-oriented (howtos, Gadget- and User script-specific docs, etc.) aimed at non-core developers (with the caveats implied by being pre-1.0 of course: performing miracles is strictly optional :)).

In T279421#8107147, @Xover wrote:

@egardner wrote:

• Archive, delete, or prune old Vue Migration Team pages as necessary (may need help from someone with admin privileges to delete pages).

Why would you delete the old wikipages? They show the historical state and how we got to where we are, and will be of interest to not just researchers but interested contributors looking for the history. Better would be to update them so that they read kinda like a Wikipedia article about that historical thing ("Foo was a dingus for flubbering the bar. It was developed and maintained by the [[Barbaz Team of Greatness]] … In 2022 it was replaced by AcmeWidget™ maintained by [[Team HotShots]].")

There are a couple of old stub pages which never got used, and I think they could just be deleted for the sake of avoiding confusion. But in general I agree – older pages can be moved to an archive (for example, content for the "Vue Migration Team", which preceded the current Design Systems Team who is spearheading Vue & Codex work).

So, in the interest of not wasting yet more volunteer time on a dead end, it'd be helpful to get at least basic documentation for this use case up and integrated somewhere.

This is something we've wanted to support for a long time (partial support exists now) but I don't think we had a dedicated task to track it. I've created one now (see T313945). The Design Systems Team is working on an updated public roadmap, and that should provide some clarity on what

In the meantime I'd say feel free to follow this task, as well as T312165 and its subtasks. On the wiki side of things, I'm currently in the process of cleaning up some Vue and DST-related documentation. There is some information relevant to gadget authors available on the following pages. Questions / feedback always welcome (either in phab or on-wiki).

• https://www.mediawiki.org/wiki/Vue.js/Guidelines
• https://www.mediawiki.org/wiki/Design_Systems_Team/Current_Status

In addition to the Guidelines and Current Status sub-pages, I've started a Built with Vue subpage that contains a table listing all MW/WMF projects using Vue of which I am currently aware. I encourage folks more familiar with any particular project on that list to update information if necessary!

https://www.mediawiki.org/wiki/Vue.js/Built_with_Vue

Clarify and organize the various phab boards, and indicate which are deprecated. We have WVUI, Vue.js, Codex, Design-Systems-Team; scope of Phab project tags feels unclear. Please clarify the Phabricator project descriptions to shed more light on this.

IMO, this has been completed, although I welcome feedback from anyone who has suggestions for making things clearer.

WVUI has been marked as deprecated and it is noted that it will be replaced with Codex. We can mark the tag as inactive once WVUI is removed from MediaWiki and no longer in use.
Vue.js is described as a general tag for Vue.js work, which is in line with the way it's currently being used.
Codex and Design-System-Team are described in-depth both on our team page and on the Codex docs site.

In T279421#8119828, @AnneT wrote:

Clarify and organize the various phab boards, and indicate which are deprecated. We have WVUI, Vue.js, Codex, Design-Systems-Team; scope of Phab project tags feels unclear. Please clarify the Phabricator project descriptions to shed more light on this.

IMO, this has been completed, although I welcome feedback from anyone who has suggestions for making things clearer.

WVUI has been marked as deprecated and it is noted that it will be replaced with Codex. We can mark the tag as inactive once WVUI is removed from MediaWiki and no longer in use.
Vue.js is described as a general tag for Vue.js work, which is in line with the way it's currently being used.
Codex and Design-System-Team are described in-depth both on our team page and on the Codex docs site.

I think those instructions are pretty clear, thank you 🙏! So if I have found a bug in Codex, I would add both the Codex and Design-System-Team tags to put it on your radar, right? And maybe also the Vue.js tag if it is related to Codex' Vue code in particular.

One thing that could maybe be improved is to link to the sections about task tracking, that you mentioned above, from the Descriptions of those Phabricator tasks. Meaning https://phabricator.wikimedia.org/project/manage/5858/ and https://phabricator.wikimedia.org/project/manage/5587/. That would have the advantage that one has an easier time actually finding those instructions exactly at the moment when one wonders how to use these tags.

PS: If Vue.js should be used as a general tag, then shouldn't it be yellow and have the tag icon, like Accessibility?

In T279421#8120016, @Michael wrote:

So if I have found a bug in Codex, I would add both the Codex and Design-System-Team tags to put it on your radar, right? And maybe also the Vue.js tag if it is related to Codex' Vue code in particular.

Adding both Codex and Design-System-Team would be ideal, although I think it's fine for people to add one or the other and the burden of triaging tasks on both boards will be on the DST.

We (the DST) aren't using the Vue.js tag for tasks that involve features or components built with Vue; we're using it for tasks that relate to Vue infrastructure. That said, I personally think it's okay for people to use the Vue.js tag as they see fit; I don't see a need to put restrictions on it.

One thing that could maybe be improved is to link to the sections about task tracking, that you mentioned above, from the Descriptions of those Phabricator tasks. Meaning https://phabricator.wikimedia.org/project/manage/5858/ and https://phabricator.wikimedia.org/project/manage/5587/. That would have the advantage that one has an easier time actually finding those instructions exactly at the moment when one wonders how to use these tags.

Good call! I've added links to both boards' descriptions.

PS: If Vue.js should be used as a general tag, then shouldn't it be yellow and have the tag icon, like Accessibility?

Done!

Thank you 🙏

As of today, all the old Vue Migration Team pages (2021 developer summit, project charter, etc) on MediaWiki have been marked with the {{historical}} template and moved under the Design Systems Team page.

These pages can still be discovered here: https://www.mediawiki.org/wiki/Design_Systems_Team#All_Subpages

I've also added the {{historical}} template to https://www.mediawiki.org/wiki/Vue.js/OOUI_migration_guide, but left it in place. If we start converting OOUI components in earnest maybe this page can be resurrected; current practice on the team seems to prefer starting fresh for each component we introduce rather than just converting existing OOUI widgets.

Does anyone want to take a stab reviewing the Design Systems Team or Vue.js pages in their current state? I would love to be able to close this task soon. Are things sufficiently clear now?

This all looks fantastic to me, @egardner - but agreed that eyes from engineering/design would be great.

Also just edited https://www.mediawiki.org/wiki/Design_Systems_Team#Initiative_OKRs since we are drafting new OKRs.