Readers/Web/Building features with cached HTML in mind

The web team often builds features that change the look and feel of the site. Given our approach to caching there are various challenges with this.

HTML for previous deploys can be retained for up to 24hrs.
CSS / JS is usually cached for only 5 minutes

This means that:

Old HTML can be served with new CSS for up to a day.
New HTML can be served with old CSS/JS for up to 5 minutes.

As a result we have various strategies for dealing with this change when writing code.

Development

When developing always be defensive in JavaScript. Always check the existence of nodes returned by querySelectorAll for example.

Use feature flagging and feature flag classes to control when to apply CSS. This allows us to easily deploy and roll back new features.

When changing HTML of existing features that are not feature flagged, you will likely need to leverage a feature class, and add new CSS on top of the existing CSS to support both the old and new versions of the page. In this situation you will also need to test against cached HTML. To do this, generate an HTML page for the last release branch and manually test it in your browser.

Script for generating cached HTML

export MW_SERVER=http://localhost:8888
export MW_SCRIPT_PATH=/w
git checkout -b newfeature
git checkout origin/wmf/1.38.0-wmf.21
wget "$MW_SERVER/$MW_SCRIPT_PATH/index.php?title=Test_page" -O cached.html
git checkout newfeature
open "$MW_SERVER/$MW_SCRIPT_PATH/cached.html"

Whenever you make a change to master, opening cached.html will load updated JavaScript and CSS assets alongside the old (cached) HTML.