Add a `group` field?

[Elchi3]

From my cataloging research (see #579), we discussed having a group field so that feature-definition bundles could be connected to a higher level platform capability.

We could for example say that "Arrays" and "Typed Arrays" are higher level platform capabilities that are made of a bunch of feature bundles:

Group "Arrays" consisting of these bundles:

• array.yml
• array-at.yml
• array-by-copy.yml
• array-copywithin.yml
• array-fill.yml
• array-find.yml
• array-findlast.yml
• array-flat.yml
• array-from.yml
• array-fromasync.yml
• array-isarray.yml
• array-iteration-methods.yml
• array-iterators.yml
• array.of.yml
• array-splice.yml

Group "Typed Arrays" consisting of these bundles:

• typed-arrays.yml
• typed-array-iteration-methods.yml
• typed-array-iterators.yml
• array-at.yml
• array-by-copy.yml
• array-copywithin.yml
• array-fill.yml
• array-find.yml
• array-findlast.yml
• array-from.yml
• array.of.yml

With this you could make some statements/calculations with the higher level group:

• Is the whole group baseline?
• If not, which feature bundles are already baseline and which aren't?
• Compute a "Arrays 2024" group (say all feature bundles baselined up to 1-1-2024)

---

As a second step, we could think about how groups relate to each other:

In #624 (comment) @foolip says:

I was thinking about "collections" as a kind of group containing arrays, sets, weak maps, etc. In the spec it'd be both indexed collections and keyed collections.

So, maybe somewhere we want to go even higher level and say that groups can form a new group:

Group "Indexed Collections" consisting of

• group: arrays
• group: typed-arrays

[Elchi3]

For illustration, I made a draft PR for a potential groups field: #649

[foolip]

In order to name groups we'll need to track them in their own YAML files which have at least a name field.

I would suggest that we rename the feature-group-definitions/ directory to just features/, and add a groups/ directory for groups. Just a name field should be enough for now. We could also add a parent field so that we can represent a tree of groups.

[foolip]

This should also change the built JSON to have this kind of structure:

{
  "features": {
    "array": {
      "group": ["collections"]
    }
  },
  "groups": {
    "collections": {
      "name": "JavaScript collections"
    }
  }
}

Open question: How is a group tree represented? A JSON tree like BCD or indirection via identifiers like for features?

[foolip]

Here's a sketch of defining groups using a single YAML file instead of a file per directory as I suggested earlier. It would be a recursively defined schema, where each group has a name and potentially subgroups, to any depth.

css:
  name: CSS
  subgroups:
    layout:
      name: Layout
html:
  name: HTML
  subgroups:
    forms:
      name: Forms
    media:
      name: Media elements
javascript:
  name: JavaScript
  subgroups:
    collections:
      name: Collections
      subgroups:
        arrays:
          name: Arrays
        typed-arrays:
          name: Typed arrays
svg:
  name: SVG
webassembly:
  name: WebAssembly

As long as the number of groups stays relatively small, it might be easier to edit and understand in YAML form. It would be converted to JSON for the published package.

It wouldn't be possible to address with compact keys like javascript.collections.arrays directly, but we could perhaps provide a helper method to do just that, so that consumers could use something like "web-features:group:javascript.collections.arrays" to identify a group. We could also transform it into a BCD-style object where a special key like __compat is used to solve the same problem.

[captainbrosset]

+1 to the above!

[jgraham]

A small drive-by comment: I'm not a big fan of "sometimes collection keys are field names, sometimes they're data". e.g. in this case subgroups is a field name, but forms is data. collections is data even though at first glance it looks like a field name. It's much more uniform to say that collection keys are always field names, and if we want things to have an id we give them an id field.

[foolip]

Here are the two structures that I've considered:

1. Identifier is the key, name (and future properties) is on a nested object, and subgroups is also on that nested object. This means we can't use subgroups to describe anything about the group itself, which is fine. Example:

css:
  name: CSS
  subgroups:
    layout:
      name: Layout

2. BCD's approach where a __-prefixed key is used to indicate that a node in the tree is an "entry", with its properties (except the identifier) on a nested object. This makes paths through the tree the shortest possible, groups.css.layout would work in JS assuming groups is the object in this example:

css:
  __info:
    name: CSS
  layout:
    __info:
    name: Layout

@jgraham can you show what you mean in the form of a YAML snippet?

[foolip]

An additional consideration here is if we want consumers to reference groups by a path, or just a bare identifier. The examples I've given lend themselves to requiring a path, like BCD, but I think that's probably a mistake. Being able to refer to "arrays" as a bare identifier means changes to the hierarchy won't affect consumers as much. It's also shorter.

So... perhaps the published data should not have any nesting, but we provide parentGroup() and childGroups() helpers for groups. This implies that group identifiers have to be unique.

We could still author groups in some other way, of course.

[jgraham]

I was thinking something like:

groups:
 - id: css
   name: CSS 
   subgroups:
     - id: layout
       name: Layout
 - id: html
   name: HTML
   subgroups: [] 

Of course you can't directly index the data structure by id that way. If that's an important property then I agree something like the BCD model where you adopt a naming convention that separates out keys-as-field-names from keys-as-data is the best option.

[foolip]

I see, thanks for the example. Since both BCD and web-features currently uses object keys as identifiers, that would be my preference. I like that it makes it impossible to even express two groups with the same identifier in the model. This means consumers won't have to even wonder if that's a possibility.

Having put together #660 for snapshots I'm now leaning more towards a single file per group again, to reuse a lot of code. But it's not that important, anything would do, and it's more important what model we expose in the published package. For that, I'm starting to think this set of helpers could work:

// Walking the group tree
getGroups(feature); // returns array
getParentGroup(group); // returns a single group or null
getChildGroups(group); // returns array
walkGroups(root); // tree walking helper of some sort

// Enumerating features
getFeatures(group);
getFeatures(snapshot);

If there's some relationship between groups and snapshots we should also expose that.