Page MenuHomePhabricator

[Spike 12hr] Should shared components be compiled for Vue.js search?
Closed, ResolvedPublicSpike

Description

The new Vue.js search experience also marks the beginning of a Wikimedia Vue.js component library. Components therein have great aspirations including that they be:

  • Efficient to develop, meeting the expectations of modern developers, and encouraging of a welcoming culture.
  • Sharable and reusable in any context within and without Wikimedia in development and production.
  • Easily composable in any combination.
  • Responsive.
  • Performant both in terms of bandwidth and computationally.
  • Accessible (including screen readers and keyboards).
  • Localizable.
  • Tested.
  • Renderable in any context within and without a browser.
  • Documented.
  • With accurately typed, well-defined, and semantically versioned APIs.
  • User-friendly styled.
  • Intelligently divided with explicit dependencies to serve different use cases.
  • Strongly patterned, idiomatic, and intentional; components are designed consistently and cohesively.
  • Favoring composition over inheritance.

Many of these goals were identified as shortcomings of T225453 or requirements in T225572, both of which were inputs to and a supporting rationale for the Vue.js RFC itself. These guiding principles are not impossible and, in the long-term, are not merely aspirational but necessary. The initial components for the new Vue.js search experience will probably fall short but nevertheless, we do not wish to repeat past mistakes and hold these objectives dear.

An initial decision that greatly impacts our ability to meet these goals is language. This task explores the tradeoffs of uncompiled and compiled options within the remits of responsible, deliberate, and isolated experimentation that the broader case study objectives this project is expected to meet to be considered successful.

This decisioning is partly dependent on the outcome of T249350 and it's implementation is informed by T249051.

Uncompiled ES5

Notable examples

Pros

  • Components built in ES5 are universally usable in any context including ResourceLoader, gadgets, and user scripts. No abstractions. What you write is what you ship. No bundling required.
  • JSDocs provide some type checking without compilation and are more common in Wikimedia currently.
  • Every web developer has basic ES5 comprehension.
  • All documentation except for WMDE's can be written in the same coding language (ES5).
  • The most conservative option.

Cons

  • No abstractions. What you write is what you ship with little flexibility. There are few programmer accomodations available.
  • JSDocs are verbose and provide limited type checking. A lot of documentation is not actually JSDocs but instead the similar but frustratingly different JSDuck, including all of Core and OOUI.
  • Code is dated in appearance and fundamental language features like let.

Compiled language

Notable examples

Pros

  • As is the case for T249350, Web can build on past experience to help establish improved patterns for the broader organization (e.g., Popups, MobileFrontend, and Vector Storybook). Web would be in a position to share expertise outwards. Popups most of all has some of Web's best code and this is due in part to its modern language choice and intentionally progressive design. We should continue to build on that work.
  • Compiled languages allow for canonical Vue.js and meet the expectations of modern developers including: Vue.js directive and ES6 shorthands are supported, templates are precompiled and scoped styles are supported.
  • ES6 and TypeScript better meet the expectations of modern developers that would like to participate.
  • As noted for ES5, JSDocs can also be used for ES6. TypeScript provides a significantly richer and more accurate typing experience that is also less verbose, "free" unit tests for all types, and a significantly better IDE experience.
  • An improved TypeScript experience via the composition API is one of the prominent major new features in Vue 3 and may be expected by third-party or incoming Vue.js developers.
  • As informed by T249350, the output consumed in MediaWiki is an NPM package or compiled output. Since the output is ES5, it works everywhere.
  • WMDE is using TypeScript extensively for their components and Vue.js work. Using TypeScript may allow many existing components to be reused and avoid significant technical debt (ref 0, ref 1, ref 2)
  • Vector already has the functionality for adding TypeScript as wanted. If a new repo is used, this configuration could easily be replicated.
  • TypeScript is well aligned with Vue's standard prop validation but occurs at compilation time instead of run time and is universal, not just for props. See related discourse on using mutations to force typing at run time.

Cons

  • As is the case for T249350, more work lands on Web define good patterns others to use as wanted.
  • Compiled code is not the current definition of canonical MediaWiki code.
  • Compiled code does not meet the expectations of some MediaWiki developers that would like to participate. For example, not everyone knows what fat arrow functions are or how to annotate types. There's a learning curve!
  • Vue 3 ain't released yet and the Vue 2 mixin experience doesn't work well with types.
  • Implies bundling and more build time dependencies.

Acceptance criteria

  • A decision is made for the Vue.js search project.
  • Feedback on this decision is solicited in the developer survey. (This means adding some nicely formed question(s) to the survey task.)
  • Any new task(s) needed to support the decision are made. E.g., Browserlist and ES5 config.
  • Documentation on wiki is revised with any learnings.

References

Event Timeline

Restricted Application changed the subtype of this task from "Task" to "Spike". · View Herald TranscriptApr 7 2020, 8:16 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript

@kostajh noted that WMDE folks (e.g., @WMDE-leszek, @Pablo-WMDE) aren't able to participate in WMF discussions on Slack so I'm noting that this task may have some overlap with WMDE's interests. This task is super skeletal so far but please subscribe if you're interested

Niedzielski renamed this task from [Spike] How should shared components be built for Vue.js search? to [Spike] Should shared components be compiled for Vue.js search?.Apr 15 2020, 12:52 AM
Niedzielski updated the task description. (Show Details)

@Niedzielski The Google Docs linked in the description is private. In the spirit of open-source can you make it public?

@Demian, I am not the owner of this internal discussion document but will make the request on your behalf.

ovasileva renamed this task from [Spike] Should shared components be compiled for Vue.js search? to [Spike 12hr] Should shared components be compiled for Vue.js search?.May 26 2020, 5:31 PM

more work lands on Web define good patterns others to use as wanted.
Implies bundling and more build time dependencies.

The encompassing size of the search deliverable and its dependencies is known to be large. The size of shared dependencies will be offset over the coming years as more projects transition to Vue.js and common component primitives but the initial deployment will not have the luxury of waiting. Its great magnitude is risky.

Irrespective of this task, compilation of the library is necessary to significantly minimize the quantity of bytes shipped and rendering overhead. This is the best we can do now to minimize the risk that the time to present typeahead search will be too sluggish in the current loading strategy (T249306#6163572). Bundling, a related activity, is required to intelligently divide code for MediaWiki and non-MediaWiki use cases.

Although not required for shipping, standard development practices are definitely a project goal. Compilation enables the strongly recommended official guidelines to use directive shorthands and self-closing components.

Given compilation and bundling are required, the overhead required for these activities is not applicable to this evaluation. This work is needed and worthwhile.

Compiled code does not meet the expectations of some MediaWiki developers that would like to participate. For example, not everyone knows what fat arrow functions are or how to annotate types. There's a learning curve!

The learning curve for MediaWiki-specific development is far greater, even alienating, for non-MediaWiki developers. We should embrace universal standards rather than trying to force others to use unnecessary requirements of our stack for which ES5-only solutions would be.

Vue 3 ain't released yet and the Vue 2 mixin experience doesn't work well with types.

Vue 3 is still not out. Vue 2 typing support is not ideal but plans to migrate to 3 are tasked (see T251974). The initial work in the prototype shows that Vue 2 will work well for the specific use case of search without many changes required for the code written.


Arguably, a bold decision and one that could be argued about for months in itself and still only be 98% in agreement. However, given the requirements for compilation, benefits offered including built in capacities for down-compiling ES6+ functionalities to ES5, type checking, and Vue.js trends, I posit that the case study is a rare opportunity for progressive change and worth starting with TypeScript for the scope of #Vue.js-Search. Feedback will be collected in the survey for this decision to see how it works in practice.

This task is ready for sign off by @holger.knust, @Anribolon, or anyone not me.

Anribolon updated the task description. (Show Details)