Overview

We need a documented process to follow when migrating Wikimedia Foundation projects to Vue. We should list out the necessary aspects of the migration plan, including potential pitfalls and contingencies, discuss them all here, then document the process on-wiki, where it can be viewed by all and maintained/updated as we get into the migration phase. Parts of the process will be universal, while others will vary based on the project and the product team.

Details

What potential pitfalls, delays, or exceptions might arise?

This list is meant to capture as many potential problems as we can identify, so the risk they introduce can be mitigated in the plan if possible.

• Introduction of production bugs/regressions
• Introduction of performance issues, or lack of performance metrics altogether
• Deployment is more complicated than anticipated, or risky
• Delays: original estimate of work was wrong, urgent bugs in other projects arise, train delays, vacations...
• For some projects, a 1:1 migration may not be ideal (e.g. older projects that are in dire need of improvements, or that were held back by technological limitations at the time of their development), and a full rebuild may be better or necessary. This would take longer and more heavily involve design and product management.
• For some projects, migration may not be an ideal use of time (e.g. older, rarely used projects that may be better off decommissioned)

What should the process cover?

1. Training: What training will be provided to product teams pre-migration? When will it be provided, and how long will the team members have to review it?
2. App planning: How will the Design Systems team collaborate with the project team to plan out the app's architecture? How will the plan be documented (e.g. in a series of Phab tickets created by the product manager or tech lead?)
3. Timeline: How will a per-project timeline be determined and documented?
   1. This should probably include a plan for maintenance post-migration, and a contingency plan for an extended timeline due to delays
4. Personnel and roles: Who will be working on the project, and what roles will they fulfill?
5. Communication plan: How will the Design Systems team and product team work together?
   1. Slack: temporarily invite Design Systems team liaison(s) to the product team slack? Create a new channel to give product teams access to the Design Systems team directly?
   2. Code review: how will product team members alert Design Systems team members that code is ready for review?
6. QTE integration: Which QTE team member(s) will be involved, and how will their work be integrated into the process?
7. Project setup: How will those working on the project for the first time set it up for local development and/or review? How will we account for the time it may take to get the project sufficiently set up locally?
   1. Note that this might only apply to the liaison(s) from the Design Systems team, but it could also apply to older projects that product team members haven't worked with for a while or ever.
8. Pre- and post-migration review: How can product team members give us feedback on their experience, especially satisfaction metrics related to OKRs and recommendations for improvements?
9. Technical specifications: How will these decisions be made and documented? (See below for a full list)

What technical specifications must be determined pre-migration?

1. Development strategy: What strategy will be used during development of the project to maintain a new Vue-ified version of the feature code without disrupting the production code?
2. QTE review and staging: How will the new Vue version be reviewed by QTE? Will there be any kind of staging environment? What about projects where any existing staging environments don't sufficiently mimic production?
3. Deployment: How will the new Vue version be deployed?
4. Testing: What unit, regression, or other testing will be completed? Should a baseline level of testing be required, or are there situations where a lack of tests is justified?
5. Code conventions: What coding standards or Vue style guide alignment will be required?
6. Vuex: Will the project require Vuex?
7. Vue version: If the project is built with Vue 2, how can we minimize the amount of work that will be needed to eventually migrate it to Vue 3? When will that migration happen, and who will do it?
8. Other Considerations: Browser/device support (if requirements diverge from the standard ones), level of no-JS support required (none, basic "read only" experience, full edit/interaction capability, etc), SEO considerations (addressed by pre-rendering content in PHP or a future Vue SSR pipeline), special performance requirements