Reading/Web/Desktop Improvements/Vue.js case study

As a part of the desktop improvements project, the Readers Web team will be building a new search widget in Vue.js. Our experience and findings throughout this process will be used to inform the future of adopting the Vue.js framework with the goal of modernizing the tools used for frontend development.

Development status is logged.

Background

Platform Evolution is one of the five pillars of the Wikimedia Foundation's Medium Term Plan. Continuously evolving our platform is crucial to our ability to design, develop, and deliver experiences to users in the browser. Currently, WMF projects still rely on the same approach to front-end development that they did a decade ago: most user interface elements are built in PHP (often without relying on templating languages), and enhanced in the browser using jQuery and our own in-house frameworks (OOJS and MobileFrontend) and UI component library (OOUI). There are many pain points associated with this way of working in 2019.

As a result, the Frontend Architecture Working Group (FAWG) created a set of recommendations that will allow a thoughtful adoption of a modern JS framework, which will provide many immediate improvements to the front-end development process at the Foundation, and will help to pave the way for further architectural improvements in the future. After conversations, including an RfC within the Foundation, as well as with the technical volunteer community, the FAWG proceeded with the recommendation of Vue.js as the first choice for a new frontend framework.

Based on this recommendation, the Web team was selected to perform a case study on adopting the Vue.js framework with the goal of modernizing the tools used for frontend development within the foundation. We have selected the search widget within the Vector skin as our trial feature. Improving our search functionality is one of the goals of the Desktop Improvements Project and we hope that this experiment will allow us to do so while investing in the future of our frontend architecture.

This pilot project will be performed as a collaboration between the Readers Web team and other engineers across the foundation. Upon completion of this pilot, we will evaluate the success of framework adoption and publish a report with recommendations for future adoption and next steps.

Updates

Week-by-week updates are available at this page.

Timeline

Milestone	Date
Finalize resource needs and development plan	December 2019
Identify and confirm resources Complete formal training	January 2019-March 2019
Conduct Research	April-May 2020
Build Iterate Deploy	June-December 2020
Post Mortem and Documentation	January 2020

Requirements

General Requirements

Vue.js and other libraries used must go through performance review. Additionally, the Performance team should be informed of any deployment timeline for the search feature specifically.
The Vue.js and other libraries used must go through security review
All parties involved must complete formal training on the framework
A written evaluation plan must be constructed and approved by all parties involved
JavaScript error logging must be available

Technical Requirements

TBD

Product Requirements

The search widget must allow for type ahead search
Search results must include the following:
- Page name
- Image (if available)
- Wikidata description (if available)
- Access to search results page
The search widget must fit within a fixed header
Intelligent loading state (e.g., show placeholder cards when content is loading)
The design is responsive for all screen sizes
Question - what happens while search is loading? (show spinner)

Nice to have

Language switching
Random button
Replacement of other iterations of the search widget:
- searchSuggest
- WMTypeAhead (only if language switching support is available)
- SearchOverlay

Design Requirements

Final design TBD. Below is a mockup of initial thoughts on design and functionality

Project Milestones

Scaffold Lay the groundwork necessary to build new Vue.js search experience. This will be iterative but care must be taken not to set ourselves up for a short-term win now at the expense of a failure later. We’d rather have the failure now and iterate past it if possible.
Build Given adequate infrastructure such as a Vue.js repo and build step, it is now time to actually start creating the user visible feature, search! Developers and designers will be able to do their “real jobs” in this phase.
Deploy The technical underpinnings have been founded, the features have been built, and search is ready to ship. This important part of the project is where we plan to throw the master switch on our test wikis, fix issues as they arise, and measure the impact every way we can.
Iterate Was it TLC or T&C that said “don’t go chasing waterfalls”? We think this work will require several iterations both at each step and across the whole effort. It’s important to always call out that waterfall development never occurs in practice and that, indeed, iteration is expected and encouraged.
Postmortem The initial iterations have concluded. We commit to collecting feedback from all involved directly with the project and surfacing it as part of a project completion report so that the work can inform and derisk all future Vue.js toolchain efforts lest we lose the lessons we have learned.

Data and metrics

The following will be instrumented:
- Selecting the search widget
- Begin of search session (user enters text)
- End of search session (user selects a search result)
- End of search session (user closes search widget)
We will be performing an A/B test of the new treatment for logged-in users for at least one of our test wikis
We will roll back the changes and iterate on the design if overall successful search sessions decrease by more than 15%

Deployment Strategy

Deploy new location for search widget (old widget)
Deploy new search widget to officewiki
Deploy new search widget to two test wikis
Run A/B test to compare old/new widgets
Deploy everywhere (default on test wikis as all other desktop improvements features)