Gruntfile: Add comments explaining CSS prefixing policy

[skip sauce]

1 files changed, 20 insertions, 6 deletions

diff --git a/Gruntfile.js b/Gruntfile.js
index 5e6dad8668..e0128d3e29 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -23,19 +23,33 @@ module.exports = function (grunt) {
   var mq4HoverShim = require('mq4-hover-shim');
   var autoprefixer = require('autoprefixer')({
     browsers: [
-      'Android 2.3',
-      'Android >= 4',
-      'Chrome >= 35',
-      'Firefox >= 31',
+      //
+      // Official browser support policy:
+      // http://v4-alpha.getbootstrap.com/getting-started/browsers-devices/#supported-browsers
+      //
+      'Chrome >= 35', // Exact version number here is kinda arbitrary
+      // Rather than using Autoprefixer's native "Firefox ESR" version specifier string,
+      // we deliberately hardcode the number. This is to avoid unwittingly severely breaking the previous ESR in the event that:
+      // (a) we happen to ship a new Bootstrap release soon after the release of a new ESR,
+      //     such that folks haven't yet had a reasonable amount of time to upgrade; and
+      // (b) the new ESR has unprefixed CSS properties/values whose absence would severely break webpages
+      //     (e.g. `box-sizing`, as opposed to `background: linear-gradient(...)`).
+      //     Since they've been unprefixed, Autoprefixer will stop prefixing them,
+      //     thus causing them to not work in the previous ESR (where the prefixes were required).
+      'Firefox >= 31', // Current Firefox Extended Support Release (ESR)
       // Note: Edge versions in Autoprefixer & Can I Use refer to the EdgeHTML rendering engine version,
       // NOT the Edge app version shown in Edge's "About" screen.
       // For example, at the time of writing, Edge 20 on an up-to-date system uses EdgeHTML 12.
       // See also https://github.com/Fyrd/caniuse/issues/1928
       'Edge >= 12',
       'Explorer >= 9',
+      // Out of leniency, we prefix these 1 version further back than the official policy.
       'iOS >= 7',
-      'Opera >= 12',
-      'Safari >= 7.1'
+      'Safari >= 7.1',
+      // The following remain NOT officially supported, but we're lenient and include their prefixes to avoid severely breaking in them.
+      'Android 2.3',
+      'Android >= 4',
+      'Opera >= 12'
     ]
   });