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.