MDN Changelog for July 2018: CDN tests, Goodbye Zones, and BCD

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:

Here’s the plan for August:

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.

A graph comparing page load time during the experiment vs. the previous week.

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.

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 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.

The compatibilty data is available as a tooltip when editing

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:

58 of these were from first-time contributors:

Other significant PRs:

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.

About John Whitlock

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

More articles by John Whitlock…