Page MenuHomePhabricator

Update Vue and Codex documentation for WMF staff and community developers
Open, HighPublic

Description

As a volunteer technical contributor, I'd like to understand which recommended technologies I should use and which ones are legacy.

MediaWiki.org
  • Publish an updated Current Status page and transclude it into other pages where necessary.
  • Create a Vue.js/Built with Vue page which contains a table of all on-wiki features that use Vue, along with the version (2 vs 3), the component library (WVUI, Codex, homebrew), current status (in development, in production, etc), delivery method, and any other relevant info along with links to Phab tasks. The table at T272885 is a good starting point.
  • Create a Vue.js/Guidelines page that is up-to-date with current ES6/Vue 3 reality. This page can be transcluded into the main Vue.js page to replace this section.
  • Archive old Vue Migration Team pages
  • Update the Vue.js/OOUI migration guide page to mention Codex (and provide up-to-date advice generally).
  • Ensure MediaWiki pages for Vue, Codex, and DST link to the appropriate Phabricator projects/boards
  • Provide performance guidelines on when/how to load Vue code (T248718, T289208) – this task is currently blocked and may need to be dealt with later, when we can get input from various stakeholders
Phabricator
  • 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.
Other documentation

Details

Other Assignee
ldelench_wmf

Related Objects

Event Timeline

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

To give a little update from the Design Systems Team perspective:

https://www.mediawiki.org/wiki/Vue.js says it's "being evaluated" but T241180 implies that evaluation was finished a year ago.

The language here has been updated to reflect that the Foundation has officially decided to adopt Vue.

Regarding Phab organization, documentation referencing the proper Phab workboards/tags, and documentation referencing the new Vue.js UI component library, these are all things the Design Systems Team will update once we create the new component library. Per the Vue.js Developer Summit, we're going to deprecate WVUI and create a new library for anyone working within the greater MediaWiki ecosystem. This work will kick off later this month. Once we have a library name and a repository we can update all the documentation accordingly.

Question for you: how do you think the Vue.js tag should be used, either according to its current usage or something that you think would be better? We're trying to figure out how best to use it in relation to our team board since lots of infrastructure-related Vue work will be part of our scope of work, but obviously not all Vue.js work in the broader sense.

these are all things the Design Systems Team will update once we create the new component library.

@AnneT: Is there any vague ETA / timeline, or specific Phab task to depend on?

Question for you: how do you think the Vue.js tag should be used, either according to its current usage or something that you think would be better? We're trying to figure out how best to use it in relation to our team board since lots of infrastructure-related Vue work will be part of our scope of work, but obviously not all Vue.js work in the broader sense.

IIUC, this got handled in T293272 by having a vague catch-all Vue.js vs Vue.js_Migration_Team_Radar under Design-Systems-Team.

these are all things the Design Systems Team will update once we create the new component library.

@AnneT: Is there any vague ETA / timeline, or specific Phab task to depend on?

@Aklapper T299138 is the task for the initial release of Codex, the new library, which will coincide with deprecation of WVUI. We are actively working on this release now. T291445 is for the 1.0 release of Codex, after which the library will be ready for wider production use.

IIUC, this got handled in T293272 by having a vague catch-all Vue.js vs Vue.js_Migration_Team_Radar under Design-Systems-Team.

Right, thanks!

Aklapper renamed this task from Document and communicate status of Vue things and future of OOUI to Document and communicate status of Vue things (Codex) and future of OOUI, WVUI, etc.Jan 20 2022, 2:42 PM
Aklapper updated the task description. (Show Details)
Aklapper updated the task description. (Show Details)

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

Aklapper added a subscriber: STH.

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: <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.

Volker_E updated the task description. (Show Details)
STH removed STH as the assignee of this task.May 26 2022, 12:24 AM

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?

ldelench_wmf updated Other Assignee, added: ldelench_wmf.
ldelench_wmf added a subscriber: ldelench_wmf.

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!

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 :)).

@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).

egardner renamed this task from Document and communicate status of Vue things (Codex) and future of OOUI, WVUI, etc to Update Vue and Codex documentation for WMF staff and community developers.Fri, Jul 29, 9:09 PM
egardner updated the task description. (Show Details)

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-Systems-Team are described in-depth both on our team page and on the Codex docs site.

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-Systems-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-Systems-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?

So if I have found a bug in Codex, I would add both the Codex and Design-Systems-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-Systems-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!