Add initial feature support definition

[ddbeck]

This starts the process of bringing data over from ddbeck/common-web-feature-mockup. The change in context makes this a little weird, so I decided to start with a single feature: cascade-layers.

Two not obvious things happen in this PR, one reasonable and one questionable:

• (the reasonable bit) I put up some guardrails for the YAML source, with prettier. I immediately goofed (forgetting to quote some strings that required them), so I set up prettier to format the YAML files. We can expand this to everything, if we want to, but for now it applies to the definition YAML files only.

• (the less reasonable bit) In Map web-features to BCD, caniuse, chromestatus, etc. #14, we decided against including this in the built results (I think). I don't know that I like how I approached this here—there's perhaps more formal and complex ways of doing this via the schema—but rather than getting stuck in the how, I thought I'd produce a simple thing that we could talk about first.

Some questions to consider:

• How do we want to mark "internal" fields? I imagine this won't be the last thing we want to hold back from publishing (e.g., I expect editorial metadata might need this treatment too). Should we do this as a sort of configuration (as I've demonstrated)? Or would we prefer something like name prefixes, annotations in the JSON schema, or something else?

• What ought to happen to "internal" data? Right now, the only way to get at constituent features data is to parse the YAML directly. Perhaps index.ts could have a development mode, that exposes everything and only drops the internal fields on building publishable packages?

• Since this is the first time it's coming up here, how do we want to handle word separators in the data? I've used camel case as that's how I prototyped it in JSON, but now that we're using YAML perhaps we'd prefer constituent-features or constituent_features (or even constituentfeatures). Prior art from related projects suggests the full range:

  • webref uses camel case
  • browser-specs uses camel case plus the occasional un-separated field (e.g., shortname)
  • BCD uses underscores (version_added)

[foolip]

For internal data, what you've done here certainly works.

The other two options that I think would work are prefixing properties with _ (pretty common in JS and Python) or putting all internal data under a internal or extra object.

[foolip]

For separators, following BCD and using underscores seems the safest, less churn if some things later move into BCD.

[foolip]

I wonder if we can't separate mappings between different data sources and make this one BCD specific for simplicty? Something like:

bcdFeatures:
  - css.at-rules.layer
  - css.at-rules.import.layer
  - api.CSSImportRule.layerName
  - api.CSSLayerBlockRule
  - api.CSSLayerBlockRule.name
  - api.CSSLayerStatementRule
  - api.CSSLayerStatementRule.nameList

[ddbeck]

I think that's a possibility, though I have a concern about what it implies about the relationship between the feature and its constituents. For instance, if I migrate something here like the mockup's array.json and we split them up by source, we might end up with something like:

localFeatures:
  - array-relative-indexing
  - array-grouping
bcdFeatures:
  - javascript.builtins.Array
  - javascript.builtins.Array.Array
  - javascript.builtins.Array.concat
  - …

If we structure the data like this, I'm concerned that it:

• Obfuscates the fact that only localFeatures plus bcdFeatures describes a complete thing (i.e., neither key alone describes the feature)
• Makes for a bad contribution experience, where it puts the focus on data sources rather than the feature description (put another way: if BCD lacks some data to accurately characterize a feature and its support, that's a problem to fix in BCD, not a constraint on what the feature is)

That said, I recognize that the form I've presented is verbose and repetitious (though I'm not 100% certain if that's your concern, exactly). I think it would be OK to be terser, use short hands, and set defaults (or some combination thereof). Some ideas along these lines:

constituents:  # less words
- query: css.at-rules.layer
  # implicit default for `source: "@mdn/browser-compat-data"`?
- bcd:css.at-rules.layer  # use some sort of source:identifier string notation?
- bcd://css.at-rules.layer  # webbier-looking version the previous line?
- css.at-rules.layer  # assume that dotted paths are BCD?

[ddbeck]

@foolip I've switched the name of the new key to underscores and merged in the usage stats from main. I was wondering if you had any more thoughts on the mapping situation. Happy to move forward with any reasonable suggestion (of which they're all reasonable, including separating the data sources). But I wanted to give you another opportunity to chime in before I moved forward on migrating more data out of the mockup.

[foolip]

I thought I had replied here last week, but no.

Unless we have another data source in mind that we could use for computing web-feature statuses I think we should simplify and optimize for the case that all constituent features are from BCD.

But I think that if I'm right about this it will quickly become evident just by trying to maintain the data, so I don't need to get my way if your hunch is different.

[foolip]

I'd prefer simplifying to make BCD-only features compact, but approving to allow any reasonable start.

[ddbeck]

Thanks for the feedback, Philip. I've made the following changes:

• Renamed constituent_features to compat_features to communicate what the values are actually used for
• Flattened the notation to dotted paths alone

I expect that we won't need to immediately figure out the feature nesting problem (e.g., suppose we have a css5 feature) and when we reach that problem, we can probably be clever-er with internal notations than ones we have to inherit from outside the repo.