Mozilla Hacks

MDN Changelog for June 2018

By John Whitlock

Posted on July 6, 2018 in MDN

Editor’s note: A changelog is “a log or record of all notable changes made to a project. [It] usually includes records of changes such as bug fixes, new features, etc.” Publishing a changelog is kind of a tradition in open source, and a long-time practice on the web. We thought readers of Hacks and folks who use and contribute to MDN Web Docs would be interested in learning more about the work of the MDN engineering team, and the impact they have in a given month. We’ll also introduce code contribution opportunities, interesting projects, and new ways to participate.

Done in June

Here’s what happened in June to the code, data, and tools that support MDN Web Docs:

Here’s the plan for July:

Shipped 100+ HTML Interactive Examples

In June, we shipped over 100 HTML interactive examples, adding quick references and playgrounds for our HTML element documentation.

On the left, the HTML is displayed, and a tab would show the CSS. On the right, the rendered HTML of a hamster image with a caption below.

HTML Interactive Example for <figcaption>

Schalk Neethling fixed the remaining blockers, such as applying an output class as a style target (PR 961), and adding some additional size options (PR 962). wbamberg wrote instructions for adding the examples to MDN, and SphinxKnight and Irene Smith pitched in to deploy them in less than 24 hours. MDN visitors have fun, informative examples on JS, CSS, and now HTML reference pages.

Irene Smith joined the MDN writer’s team in June as a Firefox Developer Content Manager. She started work right away, including helping with this project. Welcome to the team, Irene!

Shipped Django 1.11

We deployed Django 1.11 on June 6th. There are no visible changes, but also no errors for MDN visitors. Sometimes a engineering project is successful if you just get back to where you started.

Falcon Heavy rockets moments from landing

Like the Falcon rockets, we traveled far to return to the same place.

We did most of the preparation work in development environments. On June 1st, we shipped Django 1.11 to our staging environment (PR 4830). This exposed a few issues that were quick to fix, such as the logging configuration (PR 4831) and client-side translation catalogs (PR 4831). Tests in the production-like staging environment ensured the last bugs were fixed before MDN’s visitors saw them.

We’re looking ahead to the next framework update. Django 1.11 is the last to support Python 2.7, so we’ll need to switch to Python 3.6. We’ve added a Python 3 build to TravisCI, and will ratchet up compatibility over time (PR 4848). Anthony Maton started the Python 3 changes at the Mozilla All-Hands, updating tests to expect random dictionary order, a security feature enabled in Python 3.3 (PR 4851). We expect many more changes, and we plan to switch to Python 3 with Django 1.11 by the end of the year.

The next Django Long-Term Support (LTS) release will be 2.2, scheduled for April 2019. The work will be similar to the last upgrade, updating the code to be compatible with Django 1.11 through 2.2. Ryan Johnson started the process by converting to the new-style middleware, required in 2.0 (PR 4841). We plan a smooth switch to Django 2.2 by June 2019.

Shipped Tweaks and Fixes

There were 252 PRs merged in June:

32 of these were from first-time contributors:

Other significant PRs:

Planned for July

July is the start of the second half of the year, and the team is thinking about what can be done by the end of the year. We’re planning on finishing the compatibility data migration this year, and expanding interactive examples to another documentation section.

Decommission Zones

Zones are a wiki engine feature that moves a tree of pages to a different URL, and applies additional CSS for those pages. Zones also add complexity to every request, require additional testing, and are a frequent source of bugs and translation problems. Zones have more enemies than fans on the MDN staff.

We’ve been deprecating zones for a few years. We stopped using new zones as a design tool. In last year’s site redesign, we de-emphasized the style differences between zones and “standard” wiki content (PR 4348). When migrating MDN to a new data center, we added a redirects framework that can elegantly handle the custom URLs. We’re ready for the final steps.

At the Mozilla All-Hands, Ryan Johnson and wbamberg prepared to remove zones. The work took the entire week. On the engine side, custom URLs need redirects to the standard wiki URLs, and some zone styles need to be preserved (PR 4853). Zone sidebars need to be reimplemented as KumaScript sidebars, along with translations (PR 711). Finally, content needs to be changed, to add the KumaScript sidebars and to use standard wiki CSS. While the changes are large, the effect is subtle.

On the Progressive Web Apps MDN page, the zone style has an icon next to the tile, that it will lose without zone styles.

The subtle differences between zone styles and without zone styles

After the work week, we reviewed and refined the code, double-checked the changes, and clarified the plan. We’ll ship the code, update the content, and delete zones in July.

Focus on Performance

We’re wrapping up the performance audit of MDN in July. We’ve picked some key performance metrics we’d like to track, and the headline metric is how long it takes for the interactive example to be ready on CSS, JS, and HTML reference pages. Schalk Neethling is implementing the timing measurements (IE PR 967,Kuma PR 4854, and others), using the PerformanceTiming API so the measurements will be available in browser tools. We also track timing in Google Analytics, to get real-user metrics from MDN’s global audience, unless the user has requested that we don’t track them.

We’ve found several performance bottlenecks, and we’re prioritizing them to pick the quick wins and the high-impact changes. We’ll ship improvements in July and beyond.

About John Whitlock

John is a web developer working on the engine of MDN Web Docs

More articles by John Whitlock…