Consider handling feature identifier changes or aliases

[ddbeck]

Inspired by discussion on https://github.com/web-platform-dx/feature-set/pull/89.

If the feature set is based on real-world usage by web developers, then some features may need to change identifiers from time to time or accommodate multiple known names. Some possible scenarios:

• A feature is folded into a closely related feature. For instance, subgrid is subsumed by grid. At least one feature is removed and the definition of another feature changes, triggering some sort of versioning event (either at the data or package level).
• A feature has some name but official or popular usage goes in another direction or multiple directions (e.g., es6 and es2015).
• A feature is named erroneously (e.g. felxbox) and we ship with the erroneous name.

Some questions emerge:

• How do we communicate such changes to consumers? (e.g., as release notes, as structured data, or something else)
• How much should we assist consumers in following changes? (e.g., do we maintain a formerly-known-as list for each feature? do we duplicate data access under multiple names?)
• How long should we assist consumers in following changes? (e.g., do we follow a deprecation schedule for outgoing features? do we maintain historic names in perpetuity?)

The answers to some of these questions might influence how we handle versioning (if we understand versions to be a kind of identifier for a feature).

We ought to resolve this issue before a 1.0 release.

[foolip]

Thoughts on the different cases:

A feature is folded into a closely related feature. For instance, subgrid is subsumed by grid. At least one feature is removed and the definition of another feature changes, triggering some sort of versioning event (either at the data or package level).

This case is different from the others, it's about the scope of the feature changing in addition to the name. This is a very long term problem, but I think we'll be better off trying to maintain a stable tree structure and only changing the properties of the nodes of the tree. Inverting parent-child relationships would be especially complex to understand and communicate I think.

A feature has some name but official or popular usage goes in another direction or multiple directions (e.g., es6 and es2015).

For this I think we should have a concept of renaming using aliases, if we don't pick the best name first. Such aliases could remain long term if they don't get in the way.

Technically, I think this requires that we have a features.find() method that understands aliases, so that consumers that have used the original name continue to work.

A feature is named erroneously (e.g. felxbox) and we ship with the erroneous name.

If we want to get rid of error, or if we've accidentally used up a good name, I think we need a concept of deprecation and removal. We'd mark features as deprecated and make that visible in the API and release notes, and then remove them in a future major release bump.

[foolip]

My concrete proposal here is a new alias property which is a string. In case we make multiple mistakes for the same feature we'll need an array of strings, but it's not certain that we ever will.

The API can wait until later, and might also including looking features up by BCD and caniuse identifiers.

[ddbeck]

202 stakes out the optional alias property for at least the simple case of renaming something.

[foolip]

There's some additional discussion in https://github.com/web-platform-dx/web-features/issues/729. @romainmenke points out that is might refer to multiple things, and I sketched out how I think we could handle alias reuse (removal followed by later addition) if we really have to in the future.

[romainmenke]

The alias approach does offer a way for a person to intervene and resolve issues by hand. But it is a cumbersome process. You would have to scan the entire feature set and try to find the entry that has the old identifier in an alias field.

Maybe all features could have a stable machine readable id? Something like a uuid. This would never change, even if a feature is renamed.

Having such an id would make it easier for 3rd parties (like myself) to reference web-features without having to worry too much about churn.

[foolip]

Would a "get feature" helper that follows aliases make this easier to deal with? That would also console.warn when an alias was used to make it more likely it is noticed.

I'm a little bit hesitant on an ID which is guaranteed to never change, because it opens up new questions. If a feature needs to be split, which one gets to keep the ID? And with long term evolution you also have a problem akin to Ship of Theseus, does it ever become a new feature?

[romainmenke]

Would a "get feature" helper that follows aliases make this easier to deal with?

This helps with discovery and it slightly reduces the amount of work to handle changes. It is better than only having the alias field :)