Allow references to useful subsets of large features

[ddbeck]

This is probably part of #91, but I wanted to call it out specifically so I can reference it from comments.

I want to be able to reference a subset of a larger feature, when it's useful to do so, without creating a new top-level feature.

Use cases:

• To durably reference features, even after they merge together. For example, someday we'll merge array-group into array. A Baseline banner in a blog post about array-group should still show the Baseline information for that feature, not the wider/older array feature.
• To reference historically distinct but now "invisible" features. For instance, I might want to provide a Baseline status for ES5 on caniuse, which (I think) are all part of the basic javascript feature now.
• To reference a specific part of a feature for more helpful discouraged feature alternatives. For instance, I might want to reference a group of JavaScript builtins from a discouraged feature (several examples in Add several discouraged JavaScript features #2670).
• To reference a logical group of keys for compute_from overrides or to pin the age of a feature when later keys are added. Perhaps we should have a conventional initial feature, to distinguish the keys that are "original" to that feature from those which were added later.

Spamming some phrases to make this easier to find later: inner features, inset features, interior features, merged features, minor features, historic features, subfeatures.

[ddbeck]

I've written some mock consumer documentation for feature aspects that builds on the work already in progress for redirects and splits. This is intended to set us up for merges.

[jgraham]

This was discussed on matrix.

It seems like currently there's some reluctance to split out sub-features without a clear path to re-merging them later once both the parent feature and subfeature are "widely available". Unfortunately this makes the web-features data less useful because we tell authors that things are widely available when they are in fact not. It also makes the data very difficult to use for browser vendor use cases where there's a desire to find (sub) features that aren't supported in a given browser, and link bugs / standards-positions / interop proposals to specific features.

Based on the discussion on Matrix, the discussion in the governance group, and the feedback I'm getting on baseline in the wild, I think this is now the most significant data-model issue to solve.

The hard requirements are:

• It's easy to split out sub features from a larger feature
• Sub features behave just like any other feature. In particular they must have a unique id that can refer to the specific feature. They also get a name, spec link, description etc. so that they can be used in all the same contexts as a full feature
• Where it's clear what feature the sub-feature is likely to merge into, the parent feature is specified somehow from the start (so that e.g. MDN could put the sub feature banner on the page for the main feature rather than just falling back to BCD data in that case).
• Able to handle the case where it's not known upfront that a feature will later merge (we have many existing features in the repository that work like this).
• Merging doesn't lose data i.e. we can still resolve the original feature id after a merge, and tell which larger feature it's part of.

Somewhat softer requirements are:

• We keep a record of the precise BCD keys that moved from the sub feature into the parent feature, so that people can reconstruct the history or "undo" a merge if they want to impose a stronger criteria for feature selection than "widely available"

I think the aspects proposal above deals with most of the requirements, but I'm not sure how well it handles cases where the merge isn't known upfront. It also adds some complexity to the data model as one now needs to handle nested feature definitions.

As an alternative we could consider sub-features to be defined in their own YML file just like any other feature. In cases we know the sub-feature will merge into a feature later on, we pick some character in the id to indicate the parent feature e.g. :. In that case we get a definition like:

feature:sub-feature.yml

name: Sub feature
description: Some sub-feature that's expected to eventually become part of `feature`
spec: https://spec.link
compute_from:
  - api.key

Then later when merging the features we change it to:

name: Sub feature
kind: merge
redirect_target: feature
description: Some sub-feature that's expected to eventually become part of `feature`
spec: https://spec.link
compute_from:
  - api.key

and update the main feature to include all the compute_from keys (this would be checked by a lint) i.e. we use the exact same mechanism as for splits and renames.

Advantages:

• Same mechanism for anticipated merges and unanticipated merges; we just add kind: merge and redirect_target
• Backwards compatible with existing code (except for the new kind value); consumers can ingest sub-features without having special handing.
• If we don't end up merging the feature as expected for whatever reason we can just add a rename using existing mechanisms and remove the feature: prefix from the key.

Disadvantages:

• Could get messy over time, we end up with long-lived YAML files for short-lived features.
• Consumers have to parse out the parent feature name from the feature id vs it being provided as structured data.
• Merges require manual work, and undoing them is not trivial.

[foolip]

cc @jugglinmike

[ddbeck]

After some recent discussion related to this and getting some more feedback on my aspects data model proposal, I've made some adjustments to my proposal, with the largest changes as a suggestion. Here are the highlights, when it comes to the data model (keep reading for authoring):

• Anticipating merges: This was an excellent point raised by @jgraham, which I had not previously addressed. In particular, James's suggestion that "[w]here it's clear what feature the sub-feature is likely to merge into, the parent feature is specified somehow from the start" suggested to me a bidirectional relationship for candidate merges (e.g., you might declare subgrid to be as_aspect: grid§subgrid and subgrid would get an aspect redirect back to subgrid).

  I still have some uncertainty on parts of this (e.g., do we mark that backreference as being special somehow, an "unmerged" case? Or is it merely a "moved" redirect?), but it feels like a promising avenue to begin linking together our existing island features.

• Lightweight aspects: @foolip raised the possibility that some aspects might not have a distinct name, description, or spec URL compared to the feature overall (e.g., the "inception" set of keys for a feature, versus later additions). This suggested to me that non-redirect aspects are possibly lighter than a regular feature (perhaps even fully anonymous, except for an ID).

  I still have some uncertainty on this too. There's another version of lightweight aspects where the authoring is light, but inherit "missing" data from the parent feature or have some generated text. But I thought I would start with the version that puts a great onus on consumers, for discussion.

• I updated the doc to reflect the schema we actually used for redirects, so this proposal now looks less odd in places.

Note that I did not address the authoring story. We could author aspects inside of existing feature YAML files, have folders to collect related YAML files, or use a filename convention, or some combination. I wanted to focus first on the published data format, especially since we have much more flexibility when it comes to changing the authoring experience but data changes would likely be breaking.