Consider handling feature identifier changes or aliases

[ddbeck]

Inspired by discussion on #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 #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 :)

[ddbeck]

This came up in the WebDX call today. There was a request for more examples (from me), especially actual historic ones. Some semantics we'll need to deal with:

• Renames with no underlying meaning (i.e., a typo like Fix typo in file name #2484).
• Aliases with no underlying meaning, to deal with important "also known as" cases. For example, imagine we had a referrer alias to a referer feature.
• Renames because of significant feature name/API changes. For example, at one time array-group might have been plausibly called grouptomap or something—we'd want the option to give it a new, more commonly used name.
• Merges. For example, someday we'll fold array-group into array. It should be possible to safely reference that "inner" feature of array (e.g., perhaps by making array-group a pointer to some inner structure of array that retains the shape of array-group).
• Tombstoning features that didn't go anywhere. Caniuse has tons of these, like https://caniuse.com/jpeg2000. Edit: we now have a good example as import-assertions from Add feature for discouraged import assertions #2565.
• Reserved for future use. For instance, a browser is implementing a feature (but it's not in nightlies or betas yet and not in BCD), wishes to refer to its eventual feature ID, and we want there to be a way to verify that the ID is reserved, but not publish any real data for it yet until it gets closer to release. It will (eventually, hopefully) become a real feature or get tombstoned.

There was also some discussion of features that evolved a lot, such as a CSS feature with changing name and syntax. I don't have a good example for this kind of thing and would welcome more thought on that.

[tidoust]

One (identified) example is the font-stretch CSS property that is now a legacy alias name for font-width. I suppose the feature will get renamed at some point in the future. That probably fits in your "aliases" category, but not so much as "also known as", rather as "used to be known as".