Sunday, 12 August, 2018 UTC


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.
Here’s what happened in July to the code, data, and tools that support MDN Web Docs:
  • Experimented with the CDN
  • Decommissioned zones
  • Converted compatibility data
  • Shipped tweaks and fixes by merging 307 pull requests, including 58 pull requests from 43 new contributors.
Here’s the plan for August:
  • Upgrade to Elasticsearch 5.6
Done in July

Experimented with longer CDN expirations

We moved MDN Web Docs to a CDN in April 2018, and saw a 16% improvement in page load times. We shipped with 5 minute expiration times for MDN pages, so that the CDN will request a fresh copy after a short time. MDN is a wiki, and we can’t predict when a page will change. 300 seconds was a compromise between some caching for our most popular pages, and how long an author would need to wait for a changed page to be published to all visitors. 80% of visitors are getting an uncached page.
Longer cache expirations would require cache invalidation, one of the two hard things in computer science. Before committing to the work, we wanted to estimate the expected performance benefits. From July 9 to 15, Ryan Johnson bumped the timeout from 5 minutes to 48 hours (PR 4876), and we gathered the performance data.
Average page load time decreased 3% over the previous week, a small and not significant improvement. The results for different countries was mixed, some slightly improved, and some slightly worse. The outlier was China, where average page load time increased 22%, a significant decrease in performance.
Page load time in China was worse, 60% longer on July 13
The page load time varied on weekdays versus weekends as well (positive percents are shorter page load times, better for users):
Country Page Load Decrease,
Page Load Decrease,
All 1% -2%
USA 3% 3%
India 2% -7%
China -22% -35%
Japan 0% 10%
France -1% -5%
Germany 3% 3%
UK 2% 2%
Russia 0% 2%
Brazil 2% -2%
Ukraine 6% 1%
This is a successful experiment. We got an unexpected result, with minimal work to get those results. At the same time, we’re curious why the longer CDN expiration had little effect for most users, and a negative effect for China. We have some theories.
CloudFront is Amazon’s CDN, and uses the same data centers and networks as MDN’s servers. MDN is optimized for quickly serving wiki pages, so a cache miss adds only 50-100 milliseconds to a request. The primary benefit of the CDN is reducing server load, and we did see a 25% – 50% reduction in requests made to the servers, especially during peak hours.
We’re currently directing CloudFront to cache pages, but telling downstream proxies and browsers not to cache the pages. A wiki page can change after someone edits it, and we wanted to avoid several layers of caches holding on to stale copies. Downstream caches may have a bigger impact than we expect on page load, and we can try allowing caching in the next experiment.
China has country-wide policies to monitor and control internet traffic. We don’t know the details, but longer caching times result in slower processing. We saw an improvement in China moving to CloudFront, lowering the average page load time by 30%. It is possible that most of the benefit was due to removing a second domain lookup for assets. A future experiment may skip CloudFront for traffic from China.
There’s a significant difference between weekday and weekend traffic in some countries, like China and Japan. Our guess is that weekday traffic is dominated by developers using MDN for work, weekend traffic by developers using MDN for hobbies and learning. We also suspect there are differences between the capabilities of work week devices and home devices.
Finally, the results may be a limitation of CloudFront, and we would see different results with a different CDN provider.
We’ll look elsewhere for ways to speed up our page load times. For example, Schalk Neethling is working to replace icons via webfonts with SVG icons (PR 4860), and inlining short JavaScript files rather than making a request (PR 4881). We have further plans for reducing page load time, to meet our new performance goals.
Decommissioned zones
Ryan Johnson removed zones on July 24, merging PR 4853. From a user’s perspective, there are a few changes.
Custom zone URLs, like, are now at standard wiki URLs under /docs/, like There are redirects to the new URLs, so old links should continue working.
Custom zone styling is removed, and zone pages now look like other wiki pages. This is subtle on most pages, such as removing an icon next to the title. Other pages required a re-write, such as The History of MDN.
The subtle change when removing zone styles
Zone sidebars were converted to KumaScript sidebars, and added to each page in the zone, through the heroic efforts of wbamberg (PR 711 and a few others).
About 2600 lines of code were removed, about 10% of the codebase. The wiki code is now simpler, less error prone, and safer to update.

Converted compatibility data

In July of last year, the Browser Compatibility Data (BCD) project hit the milestone of over 1000 MDN pages using the new compatibility data, with about 4900 to convert. This month, there are less than 850 pages left to convert, and over 5000 MDN pages are using the new data. The steady work of the BCD team has made a huge impact on MDN and the community.
Visual Studio Code improved the accuracy of their data by adopting the BCD project in the June 2018 release. This was proposed by Pine in vscode-css-languageservice issue #102 and implemented in PR #105, with feedback from BCD and mdn/data contributor Connor Shea.
Data from BCD in VS Code as seen in Visual Studio Code.
After a long discussion, the BCD project has updated the policy for Node.js versions numbers (PR 2196, PR 2294, and others). At first, browser-style version numbers were used, such as “4”, “6”, and “8”, but the Node.js community requested “4.0.0”, “6.0.0”, and “8.0.0”, to reflect how they think of release numbers. This affected lots of files and unstuck several Node.js pull requests.
Florian Scholz went on vacation, and Daniel D. Beck took the lead on project maintenance, including shipping the npm package, now documented via PR 2480. Most of the PRs from the Paris Hack on MDN event are now merged or closed, and the project is down to 120 open PRs, representing about half of the remaining conversion work.

Shipped Tweaks and Fixes

There were 307 PRs merged in July:
  • 197 mdn/browser-compat-data PRs
  • 48 mdn/interactive-examples PRs
  • 26 mozilla/kuma PRs
  • 13 mdn/kumascript PRs
  • 6 mdn/bob PRs
  • 5 mdn/infra PRs
  • 4 mdn/learning-area PRs
  • 1 mdn/learning-area-pt-br PR
  • 1 mdn/dom-examples PR
  • 1 mdn/voice-change-o-matic PR
  • 1 mdn/web-components-examples PR
  • 1 mdn/webextensions-examples PR
  • 1 mdn/doc-linter-webextension PR
  • 1 mdn/data PR
  • 1 mdn/web-speech-api PR
58 of these were from first-time contributors:
  • Correct node support for spread (...) in object literals (BCD PR 2189), from Tobias.
  • Add NodeJS versions for some features (BCD PR 2196), from Solant.
  • Update JavaScript spread operator (...) for Node.js (PR 2262), Update Node.js versions (PR 2294), and 9 more PRs to BCD from Christopher Sahnwaldt.
  • Add browser compatibility table for <input type="checkbox"> (PR 2383), Add browser compatibility table for <input type="button"> (PR 2384), and Add browser compatibility table for <input type="search"> (PR 2385), to BCD from varun singh.
  • Add missing entity ampersands in description. (BCD PR 2397), from epistemex.
  • Add DOMStringMap (BCD PR 2401), from Ayush Poddar.
  • Add Edge support for overflow-wrap (BCD PR 2406), from Quentin Calvez.
  • Add missing browserSettings permission (BCD PR 2407), from Juraj Mäsiar.
  • Add data on window.scroll for MS Edge (BCD PR 2433), from David Wheatley.
  • Update data on <input type="color"> for Edge (BCD PR 2434), from Thomas Prochazka.
  • Add IDEA (IntelliJ, WebStorm, etc.) to .gitignore (PR 2435), and Add Node.js 8.0.0 support for JavaScript features (PR 2436), to BCD from Peter Mouland.
  • Update backdrop-filter (BCD PR 2438), from Philip Goto.
  • Add text-align’s <string> value (BCD PR 2442), from Jakob Krigovsky.
  • Add search.get, API data (BCD PR 2444), from Geoffrey De Belie.
  • Add compatibility for window.scrollTo (BCD PR 2445), from Mauro Mandracchia.
  • Add support for CSS selector :defined (BCD PR 2454), from Estelle Weyl.
  • Add support for window.scroll functions in Safari (BCD PR 2462), from Raz Goldin.
  • Mark properties defined in ECMA-262 Annex B as deprecated (BCD PR 2469), from TSlivede.
  • Add support for MediaDevices API (BCD PR 2472), from Gaurav Mahto.
  • Update Safari support for CSS property overscroll-behavior from unknown to unsupported (BCD PR 2490), from Peter Fernandes.
  • Update Safari support for Navigator.registerProtocolHandler API from unknown to unsupported (BCD PR 2499), from Lioman.
  • Move Firefox support for Server-Timing header from 59 to 61 (BCD PR 2504), from Charles Vazac.
  • Fix JS RegExp lookbehind assertion description (BCD PR 2521), from Nate Weaver.
  • Update IE’s support of CSS property text-align-last (BCD PR 2525), from Refael Iliaguyev.
  • Add Node.js 10 support for promise.finally (BCD PR 2529), from NKN1396.
  • Add Chrome support for crisp-edges as -webkit-optimize-contrast (BCD PR 2531), from Eugene Pankov.
  • Fix CSP term navigate-to (was navigation-to) (BCD PR 2532), from Malvoz.
  • Lowercase minlength attribute for <input type=password> example (Interactive Examples PR 1024), from Timo Tijhof.
  • Change <select> examples to use “placeholder label option” pattern (Interactive Examples PR 1025), from Taylor Hunt.
  • Add a new line for markdown bullet list (Interactive Examples PR 1028), from Enguerran.
  • Add balance-all value to column-fill example (Interactive Examples PR 1039), from Estelle Weyl.
  • Add id as reference for <label for=> attribute (Interactive Examples PR 1045), from Jon Borglund.
  • Make “Publish and Keep Editing” height the same as others (Kuma PR 4900), from Mihir Karbelkar.
  • Update the URL of Web Speech API (KumaScript PR 731), from Kagami Sascha Rosylight.
  • Updating Learn sidebar to add new Layout guides (PR 736), from Rachel Andrew (first contribution to KumaScript).
  • Move Writing Modes Level 4 to Candidate Recommendation (CR) (KumaScript PR 744), from Estelle Weyl.
  • Reference correct video source video file (learning-area PR 84), from Rohit Arondekar.
  • Fix “farenheit” typo (learning-area PR 85), from arda152.
  • Fix comparison operator (!==) in Event Listener (learning-area PR 86), from Mourad El garma.
  • Add folder javascript/object-basics for chapter translation (learning-area-pt-br PR 2), from Felipe Maia.
  • Change convolver to disconnect and reconnect to the audio path (voice-change-o-matic PR 15), from LUCAS GARIBALDI ALVES.
  • Use ES2015+ syntax (web-components-examples PR 8), from Kevin Nagurski.
  • Add EventRef to the list of allowed macros (PR 70), from Eric Shepherd (first contribution to Doc Linter WebExtension).
  • Maintain case consistency (web-speech-api PR 26), from utkarsh-raj.
Other significant PRs:
  • Check link format (BCD PR 2511), one of 32 Pull Requests from Claas Augner.
  • Open interactive example links in a new tab (Interactive Examples PR 1009), from Stephan Max.
  • Update node 8, dependencies (Kuma PR 4852), from me.
Planned for August
In August, we’ll continue working on new and improved interactive examples, converting compatibility data (aiming for less than 50 open PRs), switching to Python 3, improving performance, and other long-term projects.

Upgrade to Elasticsearch 5.6

Elasticsearch powers our little-loved site search, and we’re using version 2.4 in production. This version went out of support in February 2018, but our provider gave us until August to update. We used that grace period to update from Django 1.8 to 1.11. In August, we’ll update our client libraries and code so we can update to Elasticsearch 5.6, the next major release. We don’t expect many user-visible changes with the new server, but we also don’t plan to lose site search due to missing the deadline.