Naming scheme for in-development features

[jgraham]

As we move towards having web-features earlier in the feature lifecycle, there's a tension between wanting to be specific about the which "version" of a feature we're talking about for the purposes not just of browser implementation support, but also for other sources of information about early-stage features e.g. standards-positions and intent emails.

Consider e.g. CSS Masonry. There have been multiple incompatible proposals for how this should work, with varying syntax and semantics, and some of these have shipped experimental implementations in browsers. Clearly we want the "final" web feature id to be something like css-masonry. But those proposals were contemporary, so there was never a good time to "bless" one of them with the css-masonry label, and using the label to refer to multiple incompatible things would be technically challenging, and also confusing.

Even when there are not multiple contemporary proposals for a single feature, there are often substantial changes that happen during the design process, even after one implementation has shipped something. This early design may be associated with one or more negative standards positions. However later changes to the design might cause the new proposal to be assessed as positive. In such cases it makes sense for the feature label to change so that we can see the difference between what was initially proposed, and what was finally adopted.

We discussed this problem internally at Mozilla, and propose the following process to help:

• Any feature which does not yet have broad consensus gets a -proposal-<N> suffix, where N is an integer. So we might have css-masonry-proposal-1, css-masonry-proposal-2 and so on.
• The definition of consensus depends on the working mode of the relevant standards body, but for WHATWG it might be an approved PR, for W3C it might be a spec on the standards track, for TC39 it might be Stage 3, or whatever.
• Whenever a proposal undergoes substantial revision it gets a new web-feature with the next available proposal number. "Substantial" is a judgement, but it would include anything large enough to change a vendor's opinion on the proposal (e.g. by changing a standards position state), or anything with a compatibility impact. In this case the feature for the old proposal would be marked as deprecated.
• Once the feature has broad consensus, it would get the final name, and the final version of the proposal would be aliased to that (one still might need later adjustments e.g. if some implementations ship in stages, but that doesn't affect this process).

[captainbrosset]

Thanks James for filing this.

Would you be able to please provide other examples for when this would have been useful? Are there existing web-features that ought to be renamed with the -propopsal-<N> suffix you are proposing?

Unless I'm misunderstanding, CSS Masonry isn't, I think, the best example for what you're trying to convey here. The various proposals only differ at the syntax level, but all browser vendors agree on what the feature should do and that it is ultimately needed. It's just a question of how.

I think your point is more about those features that receive negative standards positions, right?
In your view, should we have named features like "File system access" file-system-access-proposal-1 instead of file-system-access?

[jgraham]

It's generally about being unambiguous in the early stages, so we can use web-features to meaningfully talk about features which are under development, without confusion about which iteration of a feature is being referred to.

CSS-Masory is IMO a relevant example because Gecko actually ships something (albeit behind a pref). That act of shipping, even when not enabled by default, seems like it ought to be enough to require minting a -proposal- feature that can refer to "the specific thing that Gecko shipped". I agree that intermediate design ideas that never reach the level of a standards-position request or an intent email wouldn't need an associated -proposal- web-feature.

web-components is another example that springs to mind where there were multiple incompatible versions of a feature, and the community adopted an ad-hoc scheme to refer to specific iterations.

So, to put that in more positive terms, a -proposal-<N> web feature would be minted in any of the following scenarios (not necessarily a comprehensive list, but all the ones that come to mind):

• A standards-position is requested from any vendor.
• An "intent" email is sent
• An origin trial is run
• An implementation is shipped, whether enabled by default or not

Of course, a feature going through multiple of those stages without substantive changes would reuse the same web-feature name. However once the changes were substantive then a new name would be created, by choosing the next available identifier. That would happen, for example, in the face of changes to resolve concerns brought up in standards-positions, or inside working groups.

In general the -proposal- suffix would be removed once the feature is on the appropriate standards track, and it's clear there's cross-vendor consensus on the design. Typically the last -proposal-<N> version would be an alias to the final unprefixed name.

In some cases we could skip this; it's not unheard of for features to land on the standards track with broad cross-vendor support before anyone implements. But that is rare.

In your view, should we have named features like "File system access" file-system-access-proposal-1 instead of file-system-access?

In that specific case the spec is still in WICG i.e. not on a standards track, so per the process described, it would indeed still have a -proposal- suffix in its name.

[ddbeck]

In general, I'm not feeling very positively toward the suffix proposal. I have three major concerns:

• I do not think it's a good idea for us to put status information into the identifier. This will create a de facto data field inside the identifier.

  I think it won't take long at all before consumers would rely on that fact, creating a new thing we can't change without breaking things for consumers. Even if I thought this was the only issue, I would prefer to do something that didn't obviously contain information instead (e.g., random, arbitrary suffixes). (If I could go back in time—or make some really exciting breakages—I'd make the IDs much more arbitrary than they are now.)

• The happy case—a small, well-scoped feature that has easy consensus and proceeds from proposal to implementation to widely available without much excitement—would require a re-IDing.

  Imagine adding a convenience method to an existing, established API. Are we really going to go through the fuss of re-IDing that feature? Moreover, who's going to be on the hook to do that work? That feels like needless bookkeeping.

• It's not obvious to me that developers would choose to distinguish between multiple proposals to satisfy a feature and the feature itself. Overall, this proposal seems to tell me a lot about why it would be good for spec authors and implementers, but very little about how this aligns to developers' understanding of what a feature is.

It's generally about being unambiguous in the early stages, so we can use web-features to meaningfully talk about features which are under development, without confusion about which iteration of a feature is being referred to.

Does there exist evidence that developers know or care about this distinction? Supposing that masonry is a good candidate for this, I'd really like to see evidence that developers think of a "masonry-1" and "masonry-2" and not "masonry."

[ddbeck]

I think @jgraham's comment in #3088 (comment) is very helpful for understanding some of the issues here. Specifically, I want to call out this line:

At the earliest stages, I as a browser vendor, would like to use web-features to link together various pieces of data about where a specific proposal for the platform is in terms of progress through the standards and implementation process.

I think this deserves emphasis: this is a new use case, which we have not specifically aspired to support (until now, maybe). Can we do it within our existing feature model (while preserving the stuff we want to do for developers)? Or does it require something new or special? Following the discussion from the WebDX call yesterday and James' comment on the other issue, I think I'm starting to see two distinct things emerge here:

• Features as we have them in web-features today. Our contributing docs describe them as "individual components of the web platform that web developers can use to achieve specific tasks."
• Proposals that describe things that developers might be able to use in the future, but can't yet (because they don't actually exist as running code).

There's no one universal moment something jumps from proposal to feature, but I feel comfortable in saying that it's rarely† earlier than shipping behind a flag or in an origin trial and absolutely no later than BCD keys existing (nowadays, detected in a beta taken a short time before promotion to stable). Somewhere in that window, ordinary developers (i.e., not browser engineers) become able to make a real web page that exercises the API, layout, etc. Once the "web developers can use" threshold of our existing model is crossed, we can define a feature without much heartache. Right now, we have 1000+ features in this mold with only a few exceptional cases to resolve; we know how to do this part.

Before that fuzzy threshold, I want to protect developers from being flooded with information about things that they definitely cannot use. I'd really regret, for example, sending every proposal—no matter how far from implementation it might be—to be ingested by caniuse or hitting OWD's tooling for finding un- and underdocumented features. My proposed process in #3088 aims to avoid this by delaying minting features that are too far in advance of becoming somehow available to developers to try out. But maybe delay isn't quite the right move.

This suggests to me to a couple of specific questions:

1. How do we distinguish a proposed, not-yet usable platform capability from something that concretely exists in a browser?
2. How do we associate a proposal artifact (e.g., an explainer) to an eventual feature, when that feature comes into existence?

James's proposal implies that a proposal and a feature are the same thing. I'm not sure they are. What do you think of a sibling namespace alongside features (like groups and snapshots), which might "graduate" to features? Or what other models might exist to make this distinction, so current consumers can continue to surface useful, usable things to developers?

† The rare case would be something like Temporal, which had sufficiently realistic polyfills well before an experimental implementation in a browser.

[jgraham]

James's proposal implies that a proposal and a feature are the same thing.

Arguably this issue proposes that the are not quite the same thing and distinguishes them via naming convention.

I understand there are concerns about relying on a naming convention, and I'm not wedded to that. But if the use case is using the feature id as a key, it's nice if it's relatively straightforward to have a single table containing all possible keys, and an obvious string representation of the key (vs proposals being conceptually in a different table/namespace with e.g. "proposal" and "iteration" fields and no canonical representation of how that maps to a string that can be put in e.g. a standards-position request).

Also, I note that the proposal here is specifically that graduation from "proposal" to "feature" isn't just about "can a developer use this", but "does this have cross-vendor buy in and has reached the corresponding stage in the standards process". For example WebRTC Plan B was a thing that developers could (and did) use for a while, but it still ended up being removed and replaced by APIs that had the properties required to reach consensus. We communicate that property indirectly in various ways (e.g. by linking to specs and standards positions), but expecting users to gather that data from multiple signals is a bit worse than asking them to infer browser support from looking at BCD data directly :)

[ddbeck]

Also, I note that the proposal here is specifically that graduation from "proposal" to "feature" isn't just about "can a developer use this", but "does this have cross-vendor buy in and has reached the corresponding stage in the standards process".

Hmm. So in this scenario, would something like import-assertions have started out as import-assertions-proposal, then stayed with that name for forever? Is there something undesirable about the way we've handled it already, treating it as a feature that was specified, shipped, discouraged, and withdrawn? (If I've done something less than good, I'd really like to know about it!)

Or what about something like webusb? As far as I know there's no active effort to get consensus on a USB feature but it's also not going away. It's just… there, useful to developers in some limited circumstances. Would you want to recharacterize it as a proposal?

And what of things that at least notionally have consensus but don't have implementations? There's a bunch of bits of CSS print layout that are apparently non-controversial but have never been implemented, despite being in specification text for as long as I can remember. Does "vendor buy in" imply some level implementation, on top of pure process obligations?

Or suppose the mirror image (I don't have a handy example right now, though I know I've seen some historically in BCD): something was accepted, shipped, and is widely available, but the specification text is stuck in an unmerged PR? It hasn't fulfilled the standards process, but it's done and dusted. What then?

[jgraham]

Hmm. So in this scenario, would something like import-assertions have started out as import-assertions-proposal, then stayed with that name for forever? Is there something undesirable about the way we've handled it already, treating it as a feature that was specified, shipped, discouraged, and withdrawn?

So IIUC that proposal made it to Stage 3, and then was dropped in favour of Import Attributes which made it to stage 4. I don't feel confident I know what the ECMA community would think is the right time to drop the "proposal" label, but let's assume for the sake of argument that it's Stage 4. In that case, in my suggested approach, the proposal would have got a name like import-assertions-proposal-1. Assuming no significant backward compatible changes to the proposal over its lifetime it would have kept that name until it was dropped, at which point it would be marked as dropped (or "discouraged") in the web-features metadata.

Basically that would be like today, except it would also be clear that it was a proposal that didn't move forward vs being a feature that was really in use.

Or what about something like webusb? As far as I know there's no active effort to get consensus on a USB feature but it's also not going away. It's just… there, useful to developers in some limited circumstances. Would you want to recharacterize it as a proposal?

Yes. It's only in WICG, not on any standards track. "proposal" is perhaps rather a generous interpretation of its status, but it's certainly an improvement over the status quo.

And what of things that at least notionally have consensus but don't have implementations?

I'd be happy with considering anything with zero implementations to be a proposal until at least one person ships (but these are also largely invisible).

Or suppose the mirror image (I don't have a handy example right now, though I know I've seen some historically in BCD): something was accepted, shipped, and is widely available, but the specification text is stuck in an unmerged PR? It hasn't fulfilled the standards process, but it's done and dusted. What then?

It remains as a proposal until someone is sufficiently motivated to do the spec work. I agree that this is an unfortunate situation, but I think the right solution is to avoid that happening as much as possible, not trying to work around it at higher levels.

[captainbrosset]

James, regarding import-assertions, you said:

in my suggested approach, the proposal would have got a name like import-assertions-proposal-1 [...] Basically that would be like today, except it would also be clear that it was a proposal that didn't move forward vs being a feature that was really in use.

But it was a feature that was really used, by many developers. At least for some time.

the proposal here is specifically that graduation from "proposal" to "feature" isn't just about "can a developer use this", but "does this have cross-vendor buy in and has reached the corresponding stage in the standards process".

This definition will create a subset of entries from our repo, which I don't think is useful to our target audience, and might even make it more difficult for them to do things on the web. At least, if that subset is made visible to devs via our consumers.

My assessment is that web developers do consider things they can use on (at least part of) the web as features, whether or not those things have cross-vendor buy-in. Developers don't wait for us to agree on features and to release specs, and often don't even know that we do. In many cases, it's desirable to use a feature, even if that feature isn't on a standards track or has vendors opposing it.

I guess my point is that, while it seems fine for us to have stricter rules about what we call the things that are standards-based and agreed upon by all vendors (maybe by using a flag of some sort), I certainly wouldn't that have a negative impact on how developers perceive the full list of APIs/features they can learn about, consider, test, send feedback about, and eventually use (even if on certain browsers only).

[captainbrosset]

Another thing to consider is that we mostly already have the data we need to display the subset of web-features that are on a standards track and with cross-vendor buy-in:

• Use browser-specs to filter out features that are not on a standards track.
• Use this standards-position to web-features mapping file (although imperfect) to filter out features with negative positions.

My point being: maybe we can achieve the use case without naming changes, extra processes, and impact to developer perception of the features.
Happy to add a page to the web-features-explorer that does this if that's useful.

[jgraham]

So to be clear here, the value of having a naming scheme for in-progress features is that having something is a prerequisite for this to be useful to vendors during the development stages of a proposal. For example if we'd taken the name masonry to mean "the original prototype that Gecko shipped", there would today be a lot of pressure to change the "masonry" feature to refer to a new version of the proposal. But if we keep changing what version of a feature a specific name refers to then it's impossible to use that feature name for understanding the state of different early-stage proposals (e.g. linking it against standards-positions, intent emails, etc.). It also puts the web-features group in the difficult position where we have to adjudicate which proposal for a feature is the one most likely to move forward, and to pick a time to update the name or the content of the feature.

My proposal solves both of those problems by introducing a scheme to coin names for early stage features that are guaranteed not to create clashes as the feature develops, and ties the provision of a final, stable, name to progress on the standards process that web features are already supposed to be going through, This means that this group is not setting itself up as a new adjudicator of feature stability, but just basing its decisions on objective data from existing standards processes.

I guess my point is that, while it seems fine for us to have stricter rules about what we call the things that are standards-based and agreed upon by all vendors (maybe by using a flag of some sort), I certainly wouldn't that have a negative impact on how developers perceive the full list of APIs/features they can learn about, consider, test, send feedback about, and eventually use (even if on certain browsers only).

I don't think this is related to the main point here. From the point of view of developers, the naming scheme is much less important than how the features are presented to end users. As you say, we already have a lot of information available that can help people make good choices here, and projects like Baseline are designed to show that data in a way that is easy to understand.

[ddbeck]

For example if we'd taken the name masonry to mean "the original prototype that Gecko shipped", there would today be a lot of pressure to change the "masonry" feature to refer to a new version of the proposal.

FWIW, we kinda did that and we have not seen any pressure to change the feature. The only suggestion to change masonry thus far has been fairly modest.

But if we keep changing what version of a feature a specific name refers to then it's impossible to use that feature name for understanding the state of different early-stage proposals

Yes, I agree that would be a bad outcome. And I think I have an idea on how to handle that which doesn't necessarily require ID churn or binding ourselves to (diverse, difficult-to-explain, and often unreliable) standards processes, but still preserves the uniqueness of distinct proposals. It's two pronged:

1. We should change our ID guidelines to prefer using entrypoints to come up with new IDs, over spec titles, headings, and other sources, unless there's unambiguous evidence that developers prefer some other way of referencing the feature.

2. Changes to spec URL values should be met with serious scrutiny and possibly trigger minting a new feature. For example, if we swap out an explainer URL for a proper spec URL, then we should check to make sure that spec aligns with the explainer (i.e., that the entrypoints have not significantly changed), our ID, and description.

I think the benefits of this approach would be:

• We'd increase the likelihood that no two proposals would expect to occupy the same ID merely by addressing the same topic.
• We'd avoid ID churn on boring proposals that proceed uneventfully to widely available.
• We'd avoid having to make judgments about which standards processes distinguish a proposal from a completed feature (e.g., look at customizable <select> as an example where a single feature rests atop many standards processes).
• We'd resolve some longstanding ambiguity about how to set IDs, especially when there's no developer usage to rely on.
• IDs would be bound more specifically to a concrete realization of a feature, rather than concept it seeks to address.

I think the risks of this approach would be:

• We'd be vulnerable to collisions when there are competing proposals for the same entrypoint. So if you had two proposals the behavior of some-property: new-magic, we'd have to look to the semantics of new-magic and invent disambiguation text for the ID. In this scenario, the first mover would get the new-magic ID. I don't know how many of these hair-splitting proposals might emerge.
• We'd have to reject "obvious" IDs (see my shadow DOM example below), at least until developers glom onto a name.

To play this out a little, here are two examples:

• Masonry: I gave masonry a bad ID (it was a very early addition to web-features, I think before we were even calling it that). Knowing what I know now about defining features and this discussion, I might've named that feature for its entry point, such as grid-template-masonry, leaving open the door to display-masonry and item-flow. There never would have been a claimant to masonry alone.

• Shadow DOM: Retrospectively, had we existed with an approach like this in 2014, we might have proceeded like this:

  • 2014: minted create-shadow-root. There'd be a temptation to call this shadow-dom—we should avoid it!
  • 2016: minted attach-shadow.
  • 2018: redirected create-shadow-root to shadow-dom-v0 and redirected attach-shadow to shadow-dom-v1, to reflect how developers talked about those things since then.

See also: #2866

[jgraham]

FWIW, we kinda did that and we have not seen any pressure to change the feature.

We also haven't been using web-features for anything other than baseline (and baseline-like) use cases so far. If we also want to use the web-features dataset to help implementors communicate about in-development features then I think the dynamics will shift from what we've seen so far.

I think I have an idea on how to handle that which doesn't necessarily require ID churn or binding ourselves to (diverse, difficult-to-explain, and often unreliable) standards processes,

If standards processes are seen as "unreliable", we have a much bigger problem. I think all web-relevant standards bodies have very clear process transitions that we can make use of.

Look at customizable <select> as an example where a single feature rests atop many standards processes).

That seems like a use case for later grouping; during the design and implementation stage coupling together proposals in different groups which might have different level of implementation priority is going to make it hard to discuss the elements of a feature, and makes it way more likely we'll have to split the feature late due to "partial" implementations.

Here are two examples:

I think these look simpler than they actually are because we have the benefit of hindsight to pick out the distinguishing features of each proposal compared to later successors.

To give an example of something that's currently in-progress: Page Embedded Permission Controls got a negative standards-position from Mozilla. However there's an ongoing discussion, and there's now a second issue for feedback on a new iteration of the proposal. In this case it's absolutely not clear, at least to me, how the feature names should have been chosen based on your scheme. But page-embedded-permission-controls-proposal-1 and page-embedded-permission-controls-proposal-2 seems quite straightforward, and doesn't require adhering to naming rules that require human validation.

In general, the process properties I'd like (as opposed to the functional properties discussed earlier) are:

• As far as possible no judgement is required; where possible we devolve decision making to the standards bodies for whom its a core function.
• Mistakes are expected, and low cost.
• Identifiers for early stage proposals are cheap to mint and require minimal external review.

The last property in particular seems key for this to be a success; if we end up in a situation where people can't get a feature id because there's some ongoing discussion about whether they picked the "best" id given the nature of the feature then we're clearly not going to get ids with all standards-positions, intent emails, etc. At that point they're no longer a reliable identifier, so we've failed to solve the problem of identifying those things.