Add compat sets to authoring format#4015
Conversation
github-actions
Bot
added
documentation
| | `group` | An optional group, or list of groups that this feature belongs to. See the definition of groups under [Create a new feature from scratch](#create-a-new-feature-from-scratch). | String, or array of strings | No | | ||
| | `caniuse` | The feature's ID on the [Can I Use](https://caniuse.com/) website. | String | No | | ||
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings | No | | ||
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. This is typically an array of strings. Less commonly, an object consisting of three arrays of strings, `core`, `modifiers`, and `incidentals`. Different validation rules apply the three lists. When in doubt, use a plain array. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings or object | No | |
There was a problem hiding this comment.
Say here which set keys end up by default? Sounds like a plain array is a shorthand for something.
| | `group` | An optional group, or list of groups that this feature belongs to. See the definition of groups under [Create a new feature from scratch](#create-a-new-feature-from-scratch). | String, or array of strings | No | | ||
| | `caniuse` | The feature's ID on the [Can I Use](https://caniuse.com/) website. | String | No | | ||
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings | No | | ||
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. This is typically an array of strings. Less commonly, an object consisting of three arrays of strings, `core`, `modifiers`, and `incidentals`. Different validation rules apply the three lists. When in doubt, use a plain array. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings or object | No | |
There was a problem hiding this comment.
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. This is typically an array of strings. Less commonly, an object consisting of three arrays of strings, `core`, `modifiers`, and `incidentals`. Different validation rules apply the three lists. When in doubt, use a plain array. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings or object | No | | |
| | `compat_features` | @mdn/browser-compat-data (BCD) entry keys (e.g., `css.properties.background-color`) that make up this feature. This is typically an array of strings. Less commonly, an object consisting of three arrays of strings, `core`, `modifier`, and `spare`. Different validation rules apply the three lists. When in doubt, use a plain array. If `compat_features` is not set in `<feature-id>.yml`, the `dist` script will populate `compat_features` in `<feature-id>.yml.dist` with BCD entry keys tagged with `web-features:<feature-id>` in BCD, if any exist. | Array of strings or object | No | |
Philip suggested to me that having the sets being alphabetically sorted would be nice. I looked around for some alternatives and kind liked "spare" as having multiple meanings (e.g., unused as in a 'spare house key', superfluous as in a 'spare heir', and to refrain as in 'to spare from'). We could also have the number agreement: core, modifier, spare (no mixing plurals). I'm going to make a change on this.
| An alternative doesn't have to be a narrow drop-in replacement for the discouraged feature but it must handle some use case of the discouraged feature. | ||
| Guide developers to the most relevant features that would help them stop using the discouraged feature. | ||
|
|
||
| ## Status overrides |
There was a problem hiding this comment.
I'm not a big fan of the location of this guideline. It would make more sense to me if this section immediately followed the Associate BCD keys with your feature, under Set the status of a feature in CONTRIBUTING.md.
This feels more closely related than our writing style guide.
Perhaps we should also move the Groups and Discouraged sections to the CONTRIBUTING.md file.
There was a problem hiding this comment.
@captainbrosset I tried doing as you suggested, but it ended up feeling pretty weird. CONTRIBUTING.md is a kind of tutorial on minting a feature. From here onward, most new feature minting should be flat compat_features, so it seemed kinda weird to introduce people to something that they should only do in exceptional circumstances.
Meanwhile, the Status overrides doc section is more of a policy: here's how to override a status and the situations when you might consider doing it. We could break up the guidelines.md file into something like style-guide.md and data-policies.md or something like that but I think it's out of scope for this PR.
That said, I did think it only fair to acknowledge the existence of overrides in CONTRIBUTING.md, so I added a cross reference with 364b592.
| The keys in `modifier` are validated to have the same status _level_ as the `core` keys (for example, if the `core` set of keys is newly available, then the keys in `modifier` must be too), but not necessarily the same Baseline dates or initial browser releases. | ||
| The keys in `spare` relate to the feature but do not affect the feature's status. | ||
|
|
||
| For example, this override sets the status on the basis of key `a` and `b`, validates that key `c` is at the same level as `core`, and ignores `x` for the purpose of calculating a status. |
There was a problem hiding this comment.
A real example would also be useful. This can be done in a separate PR though.
Without it, we're telling authors that there's another, weird, way to write features, but we're not really telling them why.
I see you wrote a "You can use an override method in the following situations" section, which is great. But I feel like a real example would go a long way.
There was a problem hiding this comment.
I tried to do this but quickly found that it's difficult to find a good example that is short and doesn't have some data oddities underneath. I'll come back to this in a follow up PR, probably when we do the conversion where I'll have to look at one in turn anyway.
This reverts commit c1123ec. This was a mistake. It won't survive long term because some of this data is non-standard.
3 participants
See the previous PR #3902 for background. This PR subsumes the changes in that PR.
This implements part one of the so-called aspects proposal, which creates a ratcheting mechanism for compat key status calculation and validation. This is a precursor to feature merging.