Add a way to show links to MDN, and show them for a number of specs. (m…

…ozilla#396, part 2)

This fixes part of mozilla#375.  It does the following:

 * adds an `mdnUrl` field to `activities.json`, using @adamroach's list in
   mozilla#375 (comment)
   which can either be a string or an array of strings (like `mozBugUrl`)

 * adds a way to show the MDN icon in the "More Info" column (which I
   commit as an asset rather than picking a glyphicon, and use via CSS
   mask).

 * adds code to validate the new field in activities.py (matching
   `mozBugUrl`)

 * adds code to add the new field for the `add` verb in `activities.py`

Co-authored-by: Martin Thomson <[email protected]>

activities.json

@@ -135,6 +135,7 @@
     "ciuName": "css-paint-api",
     "description": "An API for allowing web developers to define a custom CSS <image> with javascript, which will respond to style and size changes.",
     "id": "css-paint-api",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/CSS_Painting_API",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1302328",
     "mozPosition": "worth prototyping",
     "mozPositionDetail": "This specification allows developing prototypes of new graphical CSS features and provides an escape hatch for developers when the existing features aren't good enough for a particular piece of a web page.",
@@ -510,6 +511,7 @@
     "ciuName": "client-hints-dpr-width-viewport",
     "description": "An increasing diversity of Web-connected devices and software capabilities has created a need to deliver optimized content for each device. This specification defines an extensible and configurable set of HTTP request header fields, colloquially known as Client Hints, to address this. They are intended to be used as input to proactive content negotiation; just as the Accept header field allows user agents to indicate what formats they prefer, Client Hints allow user agents to indicate device and agent specific preferences.",
     "id": "http-client-hints",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#Client_hints",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=935216",
     "mozPosition": "non-harmful",
     "mozPositionDetail": "Architecturally, Mozilla prefers client-side solutions for retrieving alternate versions of content, such as the HTML <picture> tag. Despite these architectural preferences, we find that Client-Hints do not present a concrete harm to the web or to its users. ",
@@ -558,6 +560,7 @@
     "ciuName": "loading-lazy-attr",
     "description": "Enabling images to be fetched at a later time, when the user is likely to look at them.",
     "id": "loading-lazy-attr",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1542784",
     "mozPosition": "worth prototyping",
     "mozPositionDetail": "As currently scoped in the HTML pull request this is a reasonable addition to how images are fetched. (Note that the scope on Can I use is slightly bigger. Frames are likely a reasonable addition, but have their own set of design challenges.)",
@@ -594,6 +597,7 @@
     "ciuName": "netinfo",
     "description": "The Network Information API enables web applications to access information about the network connection in use by the device.",
     "id": "netinfo",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1057169",
     "mozPosition": "harmful",
     "mozPositionDetail": "This API provides information about a client's network connection, which allows sites to obtain additional information about clients and their environment. It is better that sites use methods that dynamically adapt to available bandwidth, as that is more accurate and likely to be applicable in the moment.",
@@ -666,6 +670,7 @@
     "ciuName": "permissions-api",
     "description": "The Permissions Standard defines common infrastructure for other specifications that need to interact with browser permissions. It also defines an API to allow web applications to query and request changes to the status of a given permission.",
     "id": "permissions",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API",
     "mozBugUrl": null,
     "mozPosition": "important",
     "mozPositionDetail": "Mozilla believes that the ability to work with user permissions is critical for user agency. There are certain aspects of the API that are not suitable for the permissions model used in Firefox and so we would like to work on improving several aspects of the API. In particular, we think that the way that status of permissions needs to more accurately reflect the different states that exist or could exist. We also think that the interactions with Feature Policy need to be better clarified. We're committed to fixing this, because permissions has become critical in making the web a more capable platform and it is important to ensure that we preserve user control over their online experience.",
@@ -870,6 +875,7 @@
     "ciuName": "streams",
     "description": "This specification provides APIs for creating, composing, and consuming streams of data that map efficiently to low-level I/O primitives.",
     "id": "streams",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Streams_API",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1128959",
     "mozPosition": "worth prototyping",
     "mozPositionDetail": "Streams are an important building block for many APIs, in particular around networking and media.",
@@ -990,6 +996,7 @@
     "ciuName": "webauthn",
     "description": "This specification defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users. Conceptually, one or more public key credentials, each scoped to a given WebAuthn Relying Party, are created by and bound to authenticators as requested by the web application. The user agent mediates access to authenticators and their public key credentials in order to preserve user privacy. Authenticators are responsible for ensuring that no operation is performed without user consent. Authenticators provide cryptographic proof of their properties to Relying Parties via attestation. This specification also describes the functional model for WebAuthn conformant authenticators, including their signature and attestation functionality.",
     "id": "webauthn",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1294514",
     "mozPosition": "important",
     "mozPositionDetail": "Public key cryptographic authentication is a major improvement in the fight against phishing, and we encourage all security-conscious web applications to implement authentication flows utilizing Web Authentication in the future.",
@@ -1002,6 +1009,7 @@
     "ciuName": "background-sync",
     "description": "This specification describes a method that enables web applications to synchronize data in the background.",
     "id": "background-sync",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/SyncManager",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1547906",
     "mozPosition": "harmful",
     "mozPositionDetail": "We're concerned that this feature would allow users to be tracked across networks (leaking private information about location and IP address and how they change over time), and that it would allow script execution and resource consumption when it isn't clear to the user that they're interacting with the site.  We might reconsider this position given evidence that these concerns can be safely addressed.",
@@ -1014,6 +1022,7 @@
     "ciuName": "mdn-api_bluetooth",
     "description": "This document describes an API to discover and communicate with devices over the Bluetooth 4 wireless standard using the Generic Attribute Profile (GATT).",
     "id": "web-bluetooth",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=674737",
     "mozPosition": "harmful",
     "mozPositionDetail": "This API provides access to the Generic Attribute Profile (GATT) of Bluetooth, which is not the lowest level of access that the specifications allow, but its generic nature makes it impossible to clearly evaluate. Like <a href=\"#webusb\">WebUSB</a> there is significant uncertainty regarding how well prepared devices are to receive requests from arbitrary sites. The generic nature of the API means that this risk is difficult to manage. The Web Bluetooth CG has opted to only rely on user consent, which we believe is not sufficient protection. This proposal also uses a blocklist, which will require constant and active maintenance so that vulnerable devices aren't exploited. This model is unsustainable and presents a significant risk to users and their devices.",
@@ -1050,6 +1059,7 @@
     "ciuName": "midi",
     "description": "This specification defines an API supporting the MIDI (Musical Instrument Digital Interface) protocol, enabling web applications to enumerate and select MIDI input and output devices on the client system and send and receive MIDI messages. It is intended to enable non-music MIDI applications as well as music ones, by providing low-level access to the MIDI devices available on the users' systems.",
     "id": "webmidi",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/MIDIAccess",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=836897",
     "mozPosition": "under consideration",
     "mozPositionDetail": null,
@@ -1074,6 +1084,7 @@
     "ciuName": "web-share",
     "description": "This specification defines an API for sharing text, links and other content to an arbitrary destination of the user's choice.The available share targets are not specified here; they are provided by the user agent. They could, for example, be apps, websites or contacts.",
     "id": "web-share",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share",
     "mozBugUrl": "https://bugzilla.mozilla.org/show_bug.cgi?id=1312422",
     "mozPosition": "worth prototyping",
     "mozPositionDetail": "This specification defines an API that invokes sharing features of the operating system, for passing information to other applications.  One risk of this is that having this as in-page user interface rather than in-browser user interface may reduce the relevance to the user of the information shown in the URL/location bar.  However, given the demand for this capability it seems like it is likely worth exposing to the Web, and we support prototyping this feature.",
@@ -1122,6 +1133,7 @@
     "ciuName": "webusb",
     "description": "This document describes an API for securely providing access to Universal Serial Bus devices from web pages.",
     "id": "webusb",
+    "mdnUrl": "https://developer.mozilla.org/en-US/docs/Web/API/USB",
     "mozBugUrl": null,
     "mozPosition": "harmful",
     "mozPositionDetail": "Because many USB devices are not designed to handle potentially-malicious interactions over the USB protocols and because those devices can have significant effects on the computer they're connected to, we believe that the security risks of exposing USB devices to the Web are too broad to risk exposing users to them or to explain properly to end users to obtain meaningful informed consent. It also poses risks that sites could use USB device identity or data stored on USB devices as tracking identifiers.",

activities.py

@@ -65,6 +65,7 @@ class ActivitiesJson(object):
         ("org", True, ["W3C", "IETF", "Ecma", "WHATWG", "Unicode", "Proposal", "Other"]),
         ("group", False, StringType),
         ("url", True, UrlType),
+        ("mdnUrl", False, UrlArrayType),
         ("mozBugUrl", False, UrlArrayType),
         ("mozPositionIssue", True, int),
         (
@@ -231,6 +232,7 @@ def __init__(self, spec_url):
             "ciuName": None,
             "org": None,
             "url": None,
+            "mdnUrl": None,
             "mozBugUrl": None,
             "mozPositionIssue": None,
             "mozPosition": u"under consideration",

index.html

@@ -38,6 +38,18 @@
       tr:not(:hover):not(:focus-within) > .link-control > a {
         visibility: hidden;
       }
+
+      .clipicon {
+        width: 1em;
+        height: 1em;
+        background: currentColor;
+      }
+
+      .clipicon-MDN {
+        -webkit-mask: url(asset/MDN.svg) center no-repeat;
+        mask: url(asset/MDN.svg) center no-repeat;
+        width: 1.20833em;
+      }
     </style>
   </head>
   <body>
@@ -122,10 +134,16 @@ <h3>legend</h3>
         var REPO_OWNER = "mozilla";
         var REPO_NAME = "standards-positions";
 
-        function iconLink(url, text, icon) {
+        function iconLink(url, text, icon, options) {
+          var iconClasses;
+          if (options && options.custom) {
+            iconClasses = `glyphicon clipicon clipicon-${icon}`;
+          } else {
+            iconClasses = `glyphicon glyphicon-${icon}`;
+          }
           /* glyphicons documented at https://getbootstrap.com/docs/3.3/components/#glyphicons */
           return `<a href='${url || "javascript:void(0)"}' title='${text}'>`
-            + `<span class='glyphicon glyphicon-${icon}' aria-hidden='true'></span>`
+            + `<span class='${iconClasses}' aria-hidden='true'></span>`
             + `<span class='sr-only'>${text}</span></a> `;
         }
 
@@ -239,6 +257,16 @@ <h3>legend</h3>
                       out += iconLink(bug, 'mozilla bug', 'wrench');
                     }
                   }
+                  if (row.mdnUrl && row.mdnUrl !== "") {
+                    // Allow either a string or an array of strings.
+                    var mdnArray = row.mdnUrl;
+                    if (!Array.isArray(mdnArray)) {
+                      mdnArray = [mdnArray];
+                    }
+                    for (var mdn of mdnArray) {
+                      out += iconLink(mdn, 'MDN', "MDN", { custom: true });
+                    }
+                  }
                   if (row.ciuName && row.ciuName !== "") {
                     out += iconLink(`https://caniuse.com/#feat=${row.ciuName}`, 'caniuse', 'tasks');
                   }