From 5341051fc92dc7fccf1a9c87825289f1484a95fb Mon Sep 17 00:00:00 2001
From: Daisuke Akatsuka <daisuke@birchill.co.jp>
Date: Mon, 24 Aug 2020 11:19:47 +0000
Subject: [PATCH] Bug 1634045: Add a README for the compatibility panel.
 r=rcaliman,Honza

Differential Revision: https://phabricator.services.mozilla.com/D87981
---
 .../client/inspector/compatibility/README.md  | 62 +++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 devtools/client/inspector/compatibility/README.md

diff --git a/devtools/client/inspector/compatibility/README.md b/devtools/client/inspector/compatibility/README.md
new file mode 100644
index 000000000000..5a04ad4d39bb
--- /dev/null
+++ b/devtools/client/inspector/compatibility/README.md
@@ -0,0 +1,62 @@
+# Compatibility Panel
+
+## Related files
+The compatibility panel consists of the following files:
+* Client:
+  * Main: `devtools/client/inspector/compatibility/`
+  * Style: `devtools/client/themes/compatibility.css`
+* Shared:
+  * MDN compatibility dataset: `devtools/shared/compatibility/dataset/`
+  * MDN compatibility library: `devtools/shared/compatibility/MDNCompatibility.js`
+* Server:
+  * Actor: `devtools/server/actors/compatibility.js`
+  * Front: `devtools/client/fronts/compatibility.js`
+  * Spec: `devtools/shared/specs/compatibility.js`
+
+## How to update the MDN compatibility data
+The Compatibility panel detects issues by comparing against official [MDN compatibility data](https://github.com/mdn/browser-compat-data). It uses a local snapshot of the dataset. This dataset needs to be manually synchronized periodically to `devtools/shared/compatibility/dataset` (ideally with every Firefox release).
+
+The subsets from the dataset required by the Compatibility panel are:
+* browsers: [https://github.com/mdn/browser-compat-data/tree/master/browsers](https://github.com/mdn/browser-compat-data/tree/master/browsers)
+* css.properties: [https://github.com/mdn/browser-compat-data/tree/master/css](https://github.com/mdn/browser-compat-data/tree/master/css).
+
+The MDN compatibility data is available as a node package ([mdn-browser-compat-data](https://www.npmjs.com/package/mdn-browser-compat-data)).
+The following node program is a sample of how to download `browsers.json` and `css-properties.json` using the node package.
+
+```javascript
+'use strict';
+
+const compatData = require("mdn-browser-compat-data");
+const fs = require("fs")
+const path = require("path")
+
+function exportData(data, fileName) {
+  const content = `${ JSON.stringify(data) }`
+
+  fs.writeFile(
+    path.resolve(
+      __dirname,
+      fileName
+    ),
+    content,
+    err => {
+      if (err) {
+        console.error(err)
+      }
+    }
+  )
+}
+
+exportData(compatData.css.properties, "css-properties.json");
+exportData(compatData.browsers, "browsers.json");
+
+```
+
+Save the JSON files created by the script to `devtools/shared/compatibility/dataset/`.
+
+Check that all tests still pass. It is possible that changes in the structure or contents of the latest dataset will cause tests to fail. If that is the case, fix the tests. **Do not manually change the contents or structure of the local dataset** because any changes will be overwritten by the next update from the official dataset.
+
+## Tests
+* Client: `devtools/client/inspector/compatibility/test`
+* MDN compatibility library: `devtools/shared/compatibility/test`
+* Server: `devtools/server/tests/browser/browser_compatibility_cssIssues.js`