diff --git a/docs/guidelines.md b/docs/guidelines.md index a6f99e2b7dc..d4e99460c02 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -260,3 +260,17 @@ Follow these guidelines when setting a `caniuse` value: Can I Use isn't perfect. Don't use `compute_from` in a way that would not make sense if the corresponding `caniuse` value didn't exist (for example, by pinning support before the introduction of an essential component of the feature). In such situations, it's better to comment out the `caniuse` value, make a `TODO` comment, and open an issue about why you did it. + +## Groups + +The `group` field references one or more groups. +You can find group definitions in the [`groups/`](../groups/) directory. + +Groups are experimental. +It might not be clear how to group features until more features have been defined. + +Don't assign features to two or more groups such that one group is an ancestor of another. +For example, don't assign a feature to both `css` and `fonts`, since `css` is the parent of `fonts`. + +Do assign features to groups when there's an opportunity for future feature composition (see [#971](https://github.com/web-platform-dx/web-features/issues/971)). +For example, several features for the JavaScript `Array` interface are members of the `array` group.