Add a features/draft/proposed/ directory an exempt it from CI

[foolip]

No description provided.

[jgraham]

I don't really understand how this is going to work. If a vendor adds a draft feature here, how do they refer to the feature in e.g. an intent to prototype email or standards-position request? If the feature is updated "later" how is one supposed to handle references to the old name in immutable data (e.g. email)?

Basically I don't understand the concept of an "unpublished web feature". I think the use cases require there to be an agreed ID for early stage features, but which tools that don't care about early stage features can filter out.

If this proposal amounts to features getting an like vendor/foo which can be used as a real id and later renamed as normal (or marked as superseded by a different feature name), then that would make sense.

[foolip]

If this proposal amounts to features getting an like vendor/foo which can be used as a real id and later renamed as normal (or marked as superseded by a different feature name), then that would make sense.

That is effectively the proposal, yes. This PR doesn't say how to refer to these features externally, but vendor/foo SGTM.

[jgraham]

That is effectively the proposal, yes.

I think we should make that explicit, and ensure that we have group agreement on the proposal. Having a feature lifecycle that makes sense across a range of usecases feels like the important part; exactly how we represent that in the repo feels like implementation details.

[ddbeck]

I'll start with my assumptions. I'm expecting a loop like this:

1. Vendor creates a draft .yml file for vendor-originating feature X.
2. web-features mints a real feature Y.
3. web-features deletes draft X and records somewhere that draft X became real feature Y.
4. Vendor checks that record and replaces their feature X identifier with real feature identifier Y (or however they want to handle that mapping on their end).

I'm also assuming that we do not expect vendors to do any reconciliation with each other (we'll do that when we mint a feature). For example, two standards positions requests on the same day could trigger the creation of two vendor drafts referring to the same feature and we don't care, as long as everyone's generating unique vendor draft IDs.

If that's right, then I think this is a good place to start. I've left some comments on some specifics.

[ddbeck]

It would be nice to have a stub/example file showing a mapping from a completed draft to a real feature ID.

Or we could have a JSON file showing former vendor draft paths (this would be nicer for us, to have the folder contain only un-minted features, but would require vendors to do a little more than not overwrite an existing file).

[ddbeck]

This has been resolved below. After the live review session with Philip, I was brought around to the idea that the resolution of a draft can and should happen in-place, rather than deleting or moving the files. While this is less convenient for me personally as a maintainer, it's less complex for the bots that are going to commit this stuff (e.g., the process for creating a draft file is, more or less, "don't clobber an existing file").

[ddbeck]

Also, FWIW, I have been reading "vendor" in the sense of "vendorization" and not that these things would be the sole domain of browser vendors. If, for instance, WPT or State of… surveys wanted to get in on this process, then that could happen here just as well.

[foolip]

@ddbeck and I live reviewed this just now. I've updated the README to say that vendor/a-feature is how you can refer to these entries, and wrote an example for how I expect this to be used.

Note that I don't think we need to publish these anywhere to start out.

[ddbeck]

I'm much happier with the examples here. I think this is enough for us to go on to start experimenting with this.

[ddbeck]

This has been resolved below. After the live review session with Philip, I was brought around to the idea that the resolution of a draft can and should happen in-place, rather than deleting or moving the files. While this is less convenient for me personally as a maintainer, it's less complex for the bots that are going to commit this stuff (e.g., the process for creating a draft file is, more or less, "don't clobber an existing file").

[ddbeck]

It's my expectation that we'll revise this to use a fully-realized example, once we've been through it once or twice.

[ddbeck]

I'm much happier with the examples here. I think this is enough for us to go on to start experimenting with this.

[jgraham]

I think this needs to consider the workflow for consumption, rather than just the publishing workflow. If these feature names are going to appear anywhere in public (explainers, s-p requests, status counters, intent emails), it needs to be possible for people to reference them just like other feature ids.

[jgraham]

If we don't publish these anywhere we still can't reference them from e.g. standards positions without recreating all the build infrastructure to know what are valid definitions.

[foolip]

If you expect to reference these in standards positions, we can publish somewhere. How about a JSON file on GitHub pages that's updated for every commit to this repo?

[jgraham]

Well, I expect you to reference them in standards positions (requests) :p

But yes, publishing them separately to the main ids would be fine for me.

[foolip]

I see, I wasn't sure how you plan to reference web-features in https://github.com/mozilla/standards-positions. If you add it to the template, then allowing proposed/* IDs there would make sense.

[foolip]

What's still missing here is building data.proposed.json and including it as a GitHub release artifact. I'm thinking it should be an object of this shape, using the README example:

{
  "html-pis": {
    "explainer": "https://github.com/WICG/declarative-partial-updates/blob/main/patching-explainer.md",
    "chromestatus": "https://chromestatus.com/feature/6534495085920256"
  }
}

If a file doesn't parse into an object, that should be a warning where maintainers will see it, but not block releases. An empty object would be used, so that consumers of data.proposed.json can always assume an object but never assume any particular properties on the object.

[jgraham]

As a consumer, something that exactly matches the normal format, but with all the fields optional (for feature definitions; "metadata: entries like moves should be identical to the normal format) would be ideal.

[foolip]

@jgraham that sounds reasonable, we'd just add a top-level "features" object I think, and maybe a few other things that consumers of the current data.json would expect.

[ddbeck]

@foolip and I had a conversation today about how to make the 'all fields optional' stuff work cooperatively with the existing schema. We talked through one idea that goes something like this:

Create a new superset schema with a kind: proposed feature type. kind: proposed would be equivalent to kind: feature, except all fields would be optional. On each release of web-features, we'd publish data.proposed.json and a schema.proposed.json, for consumers that need kind: proposed data.

On publishing the mainstream web-features package, we'd generate data.schema.json, which would be the superset schema with kind: proposed excised at build time (i.e., exactly equivalent to today's data.schema.json).

[foolip]

@ddbeck I've added the bits for publishing data.proposed.json now. The schema is hard coded.

[ddbeck]

I like this. I would like to get rid of the hard-coded schema, but I'm willing to take that part on (see #3726 (comment) for my proposed approach), if you don't have the time for it.

One optional suggestion in a line comment.

[ddbeck]

A nice to have thing here would be to extend this to .github/workflows/publish_next_web-features.yml.