Conversation
github-actions
Bot
added
schema
|
Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs). |
|
For CSS spec linking guidelines, there are some thoughts here: web-platform-dx/web-features#1785. I don't think we consider these in BCD yet, but we could decide to leave a pointer in our docs in case we want to make more decisions about this at a later point. |
|
|
||
| ## Best practices | ||
|
|
||
| In addition to the validated rules above, the following best practices have emerged: |
There was a problem hiding this comment.
Something I'd like to see here is general guidance about the number of spec URLs (e.g., when to use more than one spec URL).
There was a problem hiding this comment.
In 226c1b5 I've added that, most of the time, you want just one URL.
| Each URL must link to a specification published by a standards body or a formal proposal that may lead to such publication. | ||
| To determine whether a specification host is valid, BCD relies on data from the [w3c/browser-specs](https://github.com/w3c/browser-specs) project. | ||
|
|
||
| If a specification is listed in browser-specs and has a [standing](https://github.com/w3c/browser-specs#standing) of "good", the URL will be accepted in BCD's `spec_url` field. |
There was a problem hiding this comment.
Maybe mention exceptions. Afaik we have a list of spec URL prefixes that we allow anyhow?
There was a problem hiding this comment.
Before merging this PR, it should be helpful to review the changes over in #29223. Some changes in there probably don't align with these guidelines, and those will be a good opportunity to check them.
Overall, I agree with the guidelines, but I think it could include some special case patterns that occur in our data, mostly due to imperfections in BCD and specs.
Examples:
- BCD features grouping related features, such as cookie prefixes, or related values (e.g. "left and right values"). The fix probably is to split them up, but it would be good to acknowledge those existing case.
- BCD behavioral features in CSS that correspond to a somewhat deeply nested type in the formal definition of a property. In this case, I have found it helpful for now to capture the type chain via multiple spec URLs. Another solution in the future could be to have a separate internal field to clarify what the feature refers to, which allows the description to be developer focused.
- BCD features that combine two related yet distinct features, such as animation of the before pseudo element. I would say that setlike/maplike/iterable also falls in this category, because these features are specified by the interface declaring this, and the setlike/maplike/iterable definition.
- SVG properties are sometimes mentioned in the SVG spec but refer back to the CSS spec. I would argue that listing both spec URLs is helpful there.
- Some CSS properties have an initial definition in one level of a spec, and are completed in a subsequent diff spec. Again, listing both makes sense to me here.
- Some API Interfaces have a core definition, and are extended in other specs. While we could just mention the spec extensions on the members that are subject of the extension, I think it wouldn't hurt listing the extensions also on the interface itself.
|
|
||
| If BCD's linter complains about the provided URL, you will need to check its state within browser-specs. Common scenarios include: | ||
|
|
||
| - The specification is not yet part of browser-specs. Check whether an issue already exists; if not, open one one and ask whether the W3C would consider adding the specification. |
There was a problem hiding this comment.
| - The specification is not yet part of browser-specs. Check whether an issue already exists; if not, open one one and ask whether the W3C would consider adding the specification. | |
| - The specification is not yet part of browser-specs. Check whether an issue already exists; if not, open one and ask whether the W3C would consider adding the specification. |
|
|
||
| ### Maplikes, Setlikes, Iterables | ||
|
|
||
| When the interface has "entries", "forEach", "get", "has", "keys", "values", "@@iterator" methods and a "size" getter via "maplike", "setlike", or "iterable" IDL constructs, link to the interface containing the definition and not to the IDL standard. |
There was a problem hiding this comment.
I have argued before that referencing the IDL construct or the method defined by the construct would make it easier to identify in the BCD data where this feature comes from. Using two spec URLs, one pointing to the interface, and the other pointing to the specification of the construct member would provide clarity. Alternatively, we could capture this in a separate internal (?) field.
|
|
||
| ### Worker support, secure_context_required | ||
|
|
||
| For BCD keys named `worker_support` and `secure_context_required`, link to the main interface specification, since these IDL flags appear alongside the interface definition (for example, `[SecureContext, Exposed=(Window,Worker)]`). |
There was a problem hiding this comment.
IIRC secure_context_required is not only used for interfaces.
3 participants
Summary
I would like to move forward with better
spec_urlimplementation and validation in BCD.In order to review big PRs like #29223, I think it makes sense to paint the bigger picture, so this is what this PR does: Document the
spec_urlproperty properly and start collecting best practices as data guidelines.Test results and supporting details
No tests, this is project documentation only.
Related issues