Add many more spec_url entries based on webref data #12709

gsnedders · 2021-10-04T16:03:58Z

This is a simple addition of many more spec_url entries for api/* based on webref.

gsnedders · 2021-10-04T16:08:18Z

I think my suggestion to review this is to look at cases where it adds multiple spec_url and decide whether it's doing something sensible, as in the general (simple) case I'm not worried by the data being added.

gsnedders · 2021-10-04T16:12:44Z

Specifically, that is this subset:

diff --git a/api/HTMLCollection.json b/api/HTMLCollection.json
index eec99ac4d..e016caded 100644
--- a/api/HTMLCollection.json
+++ b/api/HTMLCollection.json
@@ -191,7 +191,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://dom.spec.whatwg.org/#dom-htmlcollection-nameditem",
+            "https://dom.spec.whatwg.org/#dom-htmlcollection-nameditem-key"
+          ]
         }
       }
     }
diff --git a/api/HTMLEmbedElement.json b/api/HTMLEmbedElement.json
index 64376e9a7..7c3459e44 100644
--- a/api/HTMLEmbedElement.json
+++ b/api/HTMLEmbedElement.json
@@ -286,7 +286,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://html.spec.whatwg.org/multipage/iframe-embed-object.html#dom-embed-src",
+            "https://w3c.github.io/webappsec-trusted-types/dist/spec/#dom-htmlembedelement-src"
+          ]
         }
       },
       "type": {
diff --git a/api/HTMLObjectElement.json b/api/HTMLObjectElement.json
index d61a873a7..0d700f090 100644
--- a/api/HTMLObjectElement.json
+++ b/api/HTMLObjectElement.json
@@ -334,7 +334,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": true
-          }
+          },
+          "spec_url": [
+            "https://html.spec.whatwg.org/multipage/obsolete.html#dom-object-codebase",
+            "https://w3c.github.io/webappsec-trusted-types/dist/spec/#dom-htmlobjectelement-codebase"
+          ]
         }
       },
       "codeType": {
diff --git a/api/HTMLScriptElement.json b/api/HTMLScriptElement.json
index 5f6ee5158..e909722b4 100644
--- a/api/HTMLScriptElement.json
+++ b/api/HTMLScriptElement.json
@@ -518,7 +518,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://html.spec.whatwg.org/multipage/scripting.html#dom-script-src",
+            "https://w3c.github.io/webappsec-trusted-types/dist/spec/#dom-htmlscriptelement-src"
+          ]
         }
       },
       "text": {
@@ -565,7 +569,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://html.spec.whatwg.org/multipage/scripting.html#dom-script-text",
+            "https://w3c.github.io/webappsec-trusted-types/dist/spec/#dom-htmlscriptelement-text"
+          ]
         }
       },
       "type": {
diff --git a/api/HTMLTableColElement.json b/api/HTMLTableColElement.json
index 5645baee0..26fe2cb01 100644
--- a/api/HTMLTableColElement.json
+++ b/api/HTMLTableColElement.json
@@ -237,7 +237,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://html.spec.whatwg.org/multipage/tables.html#dom-col-span",
+            "https://html.spec.whatwg.org/multipage/tables.html#dom-colgroup-span"
+          ]
         }
       },
       "vAlign": {
diff --git a/api/ServiceWorker.json b/api/ServiceWorker.json
index 4e650a8db..8b033ed4c 100644
--- a/api/ServiceWorker.json
+++ b/api/ServiceWorker.json
@@ -192,7 +192,11 @@
             "experimental": false,
             "standard_track": true,
             "deprecated": false
-          }
+          },
+          "spec_url": [
+            "https://w3c.github.io/ServiceWorker/#dom-serviceworker-postmessage",
+            "https://w3c.github.io/ServiceWorker/#dom-serviceworker-postmessage-message-options"
+          ]
         }
       },
       "scriptURL": {

gsnedders · 2021-10-12T15:16:54Z

cc @ddbeck @sideshowbarker

sideshowbarker · 2021-10-13T04:59:07Z

General comment: When I added the spec URLs originally, I intentionally did not add any spec URLs for features that don’t also have in MDN URL. That’s because so far the only consumers we’ve had for the spec URLs are MDN (to populate the Specifications sections) and my own https://github.com/w3c/mdn-spec-links/ (which is what adds the in-spec MDN annotations to W3C/WHATWG/WICG specs).

So on the one hand, I agree that adding spec URLs for all features for which we can identify a spec URL is potentially a good thing — in that it’s data, and who knows, some consumer other than MDN or mdn-spec-links might find good use for that data.

But on the other hand, getting the data into MDN does come at a cost. Somebody needs to review it all (which can be pretty time-consuming) — but also, because spec URLs can change and break, there’s also an ongoing maintenance cost to having the data in BCD.

For spec URLs that have an MDN URL, I have automation that runs daily to check that all the spec URLs (including the fragments/anchors) haven’t broken. And when that happens, it costs some time for me to figure out how to fix them, and raise PRs with fixes.

But me and my automation aren’t going to do that for any spec URLs that don’t have MDN URLs. Therefore, we would be putting spec URL data into BCD that can and does break at times — but nobody will be checking it to see if it’s broken, and nobody will be opening PRs with fixes.

All that said, I don’t object to this PR getting merged. But I can’t personally justify taking time to review any of it, except whatever portion of the patch might be adding spec URLs for features that also have MDN URLs.

sideshowbarker · 2021-10-13T05:51:56Z

After looking through the patch a bit, I can there are a number of cases where it’s adding spec URLs for features that do in fact also have MDN URLs in BCD. However, in every case of those which I’ve checked so far, those MDN URLs are 404s; that is, we don’t yet actually have an article in MDN for that feature.

(This is another reason why it’s a pretty bad idea for us to be adding MDN URLs to BCD for articles that don’t actually exist yet.)

in the general (simple) case I'm not worried by the data being added

Glancing through a sample of them, I agree they seem to not look incorrect — but that does not make me confident that in any particular case, it’s actually the best anchor to be using. For all the spec URLs we landed when we did the initial adding of all of them, we checked them one-by-one manually to make sure they were the best URLs to be citing. And in some non-insignificant number of cases, we ended deciding to use different URLs that were a better choice to be directing developer readers to.

gsnedders · 2021-10-13T13:06:14Z

@sideshowbarker This is, as linked above, motivated by #12685: given standard_track is currently required (if I'm reading the schema correctly), if we want to move to inferring standard_track from spec_url (or making assertions linking them) then we need to ensure we have spec_url wherever possible.

sideshowbarker · 2021-10-14T02:59:02Z

@sideshowbarker This is, as linked above, motivated by #12685: given standard_track is currently required (if I'm reading the schema correctly), if we want to move to inferring standard_track from spec_url (or making assertions linking them) then we need to ensure we have spec_url wherever possible.

ah OK yeah — that makes sense

gsnedders · 2021-10-14T12:28:23Z

Glancing through a sample of them, I agree they seem to not look incorrect — but that does not make me confident that in any particular case, it’s actually the best anchor to be using. For all the spec URLs we landed when we did the initial adding of all of them, we checked them one-by-one manually to make sure they were the best URLs to be citing. And in some non-insignificant number of cases, we ended deciding to use different URLs that were a better choice to be directing developer readers to.

I guess my other take—wrt this—is that a bad spec link, pointing to something overly specific, is probably better than no spec link.

gsnedders · 2021-10-19T16:02:28Z

https://gist.github.com/gsnedders/0a475683482552a47e65d55df7bd5289 is the script that created this, if anyone wants to review that and/or rerun it given it's likely further conflicts will arise

Remove trusted-types links, as these are redundant links

ddbeck · 2021-11-16T13:55:04Z

api/Attr.json

@@ -141,7 +141,8 @@
            "experimental": false,
            "standard_track": true,
            "deprecated": false
-          }
+          },
+          "spec_url": "https://dom.spec.whatwg.org/#dom-attr-name"


I'm not in a position (yet) to review the individual entries here, but I do want to highlight a structural problem: spec_url ought to be a sibling of support and status (usually coming before both, right after the __compat line).

It is a sibling of support and status? (It's at the end because, uh, it got added programmatically and as is often the case with JS dictionaries insertion order being used. I guess I could change the script to add it at the beginning.)

Sorry, I misread the nesting. 🤦 You're right, it's at the right place, but it would be nice to see it at the top (I realize that the actual representation is unordered, but it's nice to have a specific order in the source).

queengooborg · 2022-02-19T01:13:01Z

Hey @gsnedders, this PR is awaiting both a rebase and requested changes. Are you able and willing to come back to this PR?

queengooborg · 2022-04-28T07:02:17Z

Thanks for your work on this PR, and sharing the script you used to create it! Since there has been no response, I opened #16051 to supersede this.

gsnedders · 2022-04-28T15:52:57Z

Oops! I clearly got distracted then forgot about this, sorry!

github-actions bot added the data:api Compat data for Web APIs. https://developer.mozilla.org/docs/Web/API label Oct 4, 2021

gsnedders mentioned this pull request Oct 4, 2021

standard_track is redundant when there is spec_url #12685

Closed

mdn deleted a comment from Earthman100 Oct 13, 2021

queengooborg added the rebase needed 🚧 label Oct 14, 2021

Add many more spec_url entries based on webref data

e2d7975

gsnedders force-pushed the way-more-spec-url branch from e322741 to e2d7975 Compare October 19, 2021 16:10

squash! Add many more spec_url entries based on webref data

70e5665

Remove trusted-types links, as these are redundant links

ddbeck requested changes Nov 16, 2021

View reviewed changes

queengooborg mentioned this pull request Apr 28, 2022

Add missing spec URLs for API features #16051

Merged

queengooborg closed this Apr 28, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add many more spec_url entries based on webref data #12709

Add many more spec_url entries based on webref data #12709

gsnedders commented Oct 4, 2021

gsnedders commented Oct 4, 2021

gsnedders commented Oct 4, 2021

gsnedders commented Oct 12, 2021

sideshowbarker commented Oct 13, 2021

sideshowbarker commented Oct 13, 2021

gsnedders commented Oct 13, 2021

sideshowbarker commented Oct 14, 2021

gsnedders commented Oct 14, 2021

gsnedders commented Oct 19, 2021

ddbeck Nov 16, 2021

gsnedders Nov 16, 2021

ddbeck Nov 22, 2021

queengooborg commented Feb 19, 2022

queengooborg commented Apr 28, 2022

gsnedders commented Apr 28, 2022

Add many more spec_url entries based on webref data #12709

Add many more spec_url entries based on webref data #12709

Conversation

gsnedders commented Oct 4, 2021

gsnedders commented Oct 4, 2021

gsnedders commented Oct 4, 2021

gsnedders commented Oct 12, 2021

sideshowbarker commented Oct 13, 2021

sideshowbarker commented Oct 13, 2021

gsnedders commented Oct 13, 2021

sideshowbarker commented Oct 14, 2021

gsnedders commented Oct 14, 2021

gsnedders commented Oct 19, 2021

ddbeck Nov 16, 2021

Choose a reason for hiding this comment

gsnedders Nov 16, 2021

Choose a reason for hiding this comment

ddbeck Nov 22, 2021

Choose a reason for hiding this comment

queengooborg commented Feb 19, 2022

queengooborg commented Apr 28, 2022

gsnedders commented Apr 28, 2022