RFC 237: Exclusions in WEB_FEATURES.yml files

[jugglinmike]

Rendered

[jcscottiii]

Thanks @jugglinmike!

The goal of establishing symbolic relationships (Single Source of Truth) is fantastic and definitely the right direction for maintainability over time.

I notice the RFC leans toward a string-based micro-syntax (!#) because it keeps the YAML schema "flat" and simple for the parser. However, I believe this shifts the complexity onto the human author. (or your favorite AI haha)

I’d love for us to consider a hybrid like Schema that supports both simple strings and objects.

Example

We keep simple strings for standard paths (no visual tax), but allow objects when a rule needs metadata (like an exclusion).

features:
  - name: alerts
    files:
      - path: ./*
        exclude_ids:       # Standard YAML list, zero ambiguity
          - print
          - logging
  - name: print
    files:
      - ./print-*         # Simple file path can stay a simple string!

---

Compared to the original

features:
  - name: alerts
    files:
      - ./*
      - "!#print"
      - "!#logging"

One major benefit:

• No Custom Parsing Logic: Any standard YAML parser reads exclude_ids as a list natively. We don't need custom regex to find where the feature name starts in !#feature-name. Something I sometimes regret doing with the **

[jugglinmike]

Hi @jcscottiii! Thanks for your feedback!

One novel aspect of your proposal is that it scopes exclusions to individual path patterns. While I think that could be tenable, it's not a capability that we've specifically felt a need for.

It sounds like we're aligned on prioritizing human authors/readers. To that end, I think "scoped" exclusions may make these rules more difficult to understand since they would effectively introduce a grouping operator that hasn't been motivated by experience. (Well, not our experience, anyway. I'd be happy to hear about any instances where you wanted it!)

How would you feel about expressing exclusions with a standalone object so that each list item could be either a string value or a dict with a single key (namely, exclude_ids)? For example:

 features:
   - name: alerts
     files:
-      - path: ./*
-        exclude_ids:       # Standard YAML list, zero ambiguity
+      - ./*
+      - exclude_ids:       # Standard YAML list, zero ambiguity
           - print
           - logging
   - name: print
     files:
       - ./print-*         # Simple file path can stay a simple string!

Anecdotally, I've only observed a small number (read: 1 to 3) of exclusions per feature entry, so a nested list like exclude_ids might be more structure than we truly need. I'm curious about simplifying it further to a string value for a key named exclude_id (despite the bit of repetition it adds to the running example):

 features:
   - name: alerts
     files:
-      - path: ./*
-        exclude_ids:       # Standard YAML list, zero ambiguity
-          - print
-          - logging
+      - ./*
+      - exclude_id: print   # Standard YAML string, zero ambiguity
+      - exclude_id: logging # Standard YAML string, zero ambiguity
   - name: print
     files:
       - ./print-*         # Simple file path can stay a simple string!

...but I don't feel this flattening would have a huge impact on ergonomics, so I could go either way!

In any case (in your proposal and in my suggested amendments), the ./ prefix is not technically necessary. Are you suggesting it should become mandatory?

[jcscottiii]

@jgraham mentioned that this should be a set of rules to web-feature-ids. Something like this:

	file-1.html: css-flexbox
	file-2.html: css-grid
	*: css-multicol

I'll let @jgraham provide a more thorough review.

[jugglinmike]

A bit more context for the benefit of tomorrow's RFC triage call:

Since this RFC is about streamlining the metadata, here's an approximation of its impact. While the syntax is still under consideration, that patch shows the order of magnitude: "130 files changed, 275 insertions(+), 791 deletions(-)"

Until recently, WPT didn't formally document the WEB_FEATURES.yml files. We landed some documentation last week, so you can now find it online at https://web-platform-tests.org/writing-tests/out-of-band-metadata.html

Looking forward to discussing more tomorrow!

[jgraham]

@jgraham mentioned that this should be a set of rules to web-feature-ids

Yes.

Mapping feature ids to filename patterns makes sense if you are trying to work out "which files are part of this feature". You find the id you care about and then evaluate the given rules against all the files in the directory. That is indeed a common use case for this data, but critically it's a use case that's basically always automated.

On the other hand if you have one file and want to know what features it will correspond to you have to evaluate the full set of rules. That's a use case you have when adding a file when you want to know if it will be correctly labelled, or if a rule update is required. Typically that use case isn't automated.

So if we want to optimise for the latter, we should look to make it as easy as possible to figure out what features correspond to a given file. In that case having the rules be a list of patterns that could apply and stopping on the first that does apply seems likely to be much easier to work with e.g.

*-grid-*: [css-grid, css-multicol]
*-flex-*: [css-flexbox, css-multicol]
*: css-multicol

There is arguably a bug there that a file which has both -grid- and -flex in it would only be labelled as css-grid and css-multicol. In theory that seems bad. In practice it seems likely to be fine to fix it by adding another rule like:

*-grid-flex-*: [css-grid, css-flexbox, css-multicol]

and just assuming that people can follow a naming convention rather than requiring a perfectly general syntax. In particular, I think that once you start making things additive you end up back at the starting point for this RFC which is "we need to invent an exclusion mechanism so that some rules don't apply in some cases" and then you're back at it being really hard for a human to correctly deduce the impact of the rules.