Mozilla Marketing Engineering & Operations blog

Kuma Report, August 2017

, by John Whitlock

Here’s what happened in August in Kuma, the engine of MDN Web Docs:

  • Launched beta of interactive examples
  • Continued work on the AWS migration
  • Prepared for KumaScript translations
  • Refined the Browser Compat Data schema
  • Shipped tweaks and fixes

Here’s the plan for September:

  • Establish maintenance mode in AWS

Done in August

Launched beta of interactive examples

On August 29, we launched the interactive examples. We’re starting with showing them to 50% of anonymous users, to measure the difference in site speed. You can also visit the new pages directly. See the interactive editors in beta post on Discourse for more details. We’re collecting feedback with a short survey. See the “take our survey” link below the new interactive example.

We’ve already gotten several rounds of feedback, by showing early iterations to Mozilla staff and to the Brigade, who helped with the MDN redesign. Schalk, Stephanie, Kadir, and Will Bamberg added user interviews to our process. They recruited web developers to try out the new feature, watched how they used it, and adjusted the design based on the feedback.

One of the challenging issues was avoiding a scrollbar, when the <iframe> for the interactive example was smaller than the content. The scrollbar broke the layout, and made interaction clumsy. We tried several rounds of manual iframe sizing before implementing dynamic sizing using postMessage to send the desired size from the client <iframe> to the MDN page. (PR 4361).

Another change from user testing is that we began with deployment to S3 behind a CDN, rather than waiting until after beta testing. Thanks to Dave Parfitt for quickly implementing this (PR 149).

It will take a while to complete the beta testing and launch these six pages to all users. Until then, we still have the live samples. Stephanie Hobson recently improved these by opening them in a new tab, rather than replacing the MDN reference page. (PR 4391).

Continued work on the AWS migration

We’re continuing the work to rehost MDN in AWS, using Kubernetes. We track the AWS migration work in a GitHub project, and we’re getting close to production data tests.

In our current datacenter, we use Apache to serve the website (using mod_wsgi). We’re not using Apache in AWS, and in August we updated Kuma to take on more of Apache’s duties, such as serving files from MDN’s distant past (PR 4365 from Ryan Johnson) and handling old redirects (PR 4231 from Dave Parfitt).

We are currently using MySQL with a custom collation utf8_distinct_ci. The collation determines how text is sorted, and if two strings are considered to be equal. MySQL includes several collations, but they didn’t allow the behavior we wanted for tags. We wanted to allow both “Reference” and the French “Référence”, but not allow the lower-case variants “reference” and “référence”. The custom collation allowed us to do this while still using our tagging library django-taggit. However, we can’t use a custom collation in AWS’s RDS database service. The compromise was to programmatically rename tags (they are now “Reference” and “Référence (2)”), and switch to the standard utf8_general_ci collation, which still prevents the lowercase variants (PR 4376 by John Whitlock). After the AWS migration, we will revisit tags, and see how to best support the desired features.

Prepared for KumaScript translations

There was some preparatory work toward translating KumaScript strings in Pontoon, but nothing shipped yet. The locale files have been moved from the Kuma repository to a new repository, mozilla-l10n/mdn-l10n. The Docker image for KumaScript now includes the locale files. Finally, KumaScript now lives at mdn/kumascript, in the mdn Github organization.

There are additional tasks planned, to use 3rd-party libraries to load translation files, apply translations, and to extract localizable strings. However, AWS will be the priority for the rest of September, so we are not planning on taking the next steps until October.

Refined the Browser Compat Data schema

Florian Scholz and wbamberg have finished a long project to update the Browser Compatibility Data schema. This included a script to migrate the data (BCD PR 304), and a unified {{compat}} macro suitable for compatibility tables across the site (KumaScript PR 272). The new schema is used in release 0.0.4 of mdn-browser-compat-data.

The goal is to convert all the compatibility data on MDN to the BCD format. Florian is on track to convert the JavaScript data in September. Jean-Yves Perrier has made good progress on migrating HTML compatibility data with 7 merged PRs, starting with PR 279.

Shipped Tweaks and Fixes

There were many PRs merged in August:

Many of these were from external contributors, including several first-time contributions. Here are some of the highlights:

Planned for September

Work will continue to migrate to Browser Compat Data, and to fix issues with the redesign and the new interactive examples.

Establish Maintenance Mode in AWS

In September, we plan to prepare a maintenance mode deployment in AWS, and send it some production traffic. This will allow us to model the resources needed when the production environment is hosted in AWS. It will also keep MDN data available while the production database is transferred, when we finalize the transition.

Related Posts