Order flag properties

[Elchi3]

Summary

To update BCD programmatically, for example from the OWD Collector project, diffs are cleaner when ordering is guaranteed. We already have this for several structures. I'm currently working on adding support for collecting flag data to the Collector project and I would benefit from a stable property order in the flag object.

This PR updates stringify-and-order-properties.js and enforces sorting:

1. type
2. name
3. value_to_set

And then I ran npm run fix, to fix the data.

Test results and supporting details

I added a test to stringify-and-order-properties.test.js

Related issues

None, I think.

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[ddbeck]

A little bikeshedding for you, @Elchi3. Do you know how frequent one sort order is versus another?

It feels like type comes first a lot and I kinda like it appearing first, since it's the "outer" context where you set the flag (so it's a bit like describing a menu, as in File → Print…).

But I suppose the "right" thing to do is to use the most frequent existing sort order (or to put this another way, to modify the fewest instances), to limit conflicts to open PRs.

[caugner]

It feels like type comes first a lot and I kinda like it appearing first, since it's the "outer" context where you set the flag (so it's a bit like describing a menu, as in File → Print…).

I would argue name is more important so it should come first, just like we put "description" first. For me, the type is an historical artifact that mostly isn't necessary, because runtime flags can usually be distinguished from prefs by leading -.

[Elchi3]

I have no strong feelings. As you can see with my second commit, the diff is smaller with type first.

[caugner]

But I suppose the "right" thing to do is to use the most frequent existing sort order (or to put this another way, to modify the fewest instances), to limit conflicts to open PRs.

I don't think we should care about minimizing changes, or limiting conflicts to open PRs. There are only 6 PRs that change flag data:

• Verify and update Firefox feature flag data #30012 (authored by me)
• Lint that a child feature's version range is inside its parent's range #30002 (authored by me)
• Updates for Chrome 154 beta #30429
• Node.js 15.3.0…26.0.0 #29619 (authored by me)
• added support for specific named-features #30464

Resolving the merge conflicts should be straight-forward in all cases.

[caugner]

How would we feel about allowing …

{
  "flags": ["Contact Picker API"],
  // …
  "flags": ["-unstable-webgpu"],
}

… and replacing those as build time by:

{
  "flags": [{"name": "Contact Picker API", "type": "preference"}],
  // …
  "flags": [{"name": "-unstable-webgpu", "type": "runtime_flag"}],
}

If we're okay with that, we can make that change first, and then I don't have strong opinions about the order of the expanded form (where a specific pref value needs to be set).

[Elchi3]

because runtime flags can usually be distinguished from prefs by leading -.

I don't think that's true. See https://peter.sh/experiments/chromium-command-line-switches/

[ddbeck]

How would we feel about allowing … [a shorthand notation for flags]

No, I'm not a fan of that. Flags are a fairly uncommon kind of data and I don't think we should increase magic (and complexity) on things that are the much less likely to get scrutiny than more common patterns in our data.

Anyway, I still like the smaller diff with type first. In the absence of a clear reason to choose one sort over another, aligning to the status quo like a good option. And if someone still wants a different sort, then they can advocate for it affirmatively in a follow up PR.

(Also, if we're nominating things to invest new linting effort into, I'd like to return to the idea of allowlisting flag names in the browser .json files, so other consumers can benefit too.)

[caugner]

I don't think that's true. See peter.sh/experiments/chromium-command-line-switches

I don't see any preference starting with - or any runtime flag (aka switch) not starting witih - in that list. Here is an inventory of flags currently in BCD:

preference
  chrome
    #enable-experimental-web-platform-features: 159
    #enable-jxl-image-format: 1
    #extension-apis: 1
    #local-network-access-check: 1
    #web-app-install-element: 16
    #web-app-installation-api: 3
    #web-machine-learning-neural-network: 125
    WebAuth: 1
    enable-experimental-web-platform-features: 27
  edge
    #edge-llm-prompt-api-for-phi-mini: 13
    enable-experimental-web-platform-features: 31
  firefox
    browser.dom.window.dump.enabled: 1
    dom.compression_streams.zstd.enabled: 2
    dom.css_pseudo_element.enabled: 3
    dom.enable_container_timing: 14
    dom.headingoffset.enabled: 4
    dom.imagecapture.enabled: 4
    dom.indexedDB.experimental: 3
    dom.multiple_import_maps.enabled: 1
    dom.payments.request.enabled: 33
    dom.payments.request.supportedRegions: 24
    dom.permissions.revoke.enable: 1
    dom.screenBrightnessProperty.enabled: 1
    dom.screenEnabledProperty.enabled: 1
    dom.security.featurePolicy.webidl.enabled: 7
    dom.select.customizable_select.enabled: 3
    dom.serviceWorkers.navigationPreload.enabled: 1
    dom.shadowdom.referenceTarget.enabled: 4
    dom.vr*: 7
    dom.vr.enabled: 69
    dom.webnotifications.requireinteraction.enabled: 1
    dom.webshare.enabled: 4
    javascript.options.experimental.regexp_buffer_boundaries: 1
    javascript.options.experimental.wasm_esm_integration: 1
    layout.css.appearance-base.enabled: 3
    layout.css.custom-media.enabled: 2
    layout.css.element-content-none.enabled: 1
    layout.css.fit-content-function.enabled: 12
    layout.css.getBoxQuads.enabled: 3
    layout.css.heading-selector.enabled: 2
    layout.css.inverted-colors.enabled: 1
    layout.css.line-clamp.enabled: 2
    layout.css.moz-submit-invalid.enabled: 1
    layout.css.prefers-reduced-transparency.enabled: 1
    layout.css.scroll-driven-animations.enabled: 2
    layout.css.text-box.enabled: 5
    media.mediasource.experimental.enabled: 2
    media.track.enabled: 27
    media.webspeech.recognition.enable: 37
    network.cookie.sameSite.laxByDefault: 1
    network.cookie.sameSite.schemeful: 1
    network.cors_preflight.authorization_covered_by_wildcard: 1
    network.http.dictionaries.enable: 8
    network.http.idempotencyKey.enabled: 1
    security.integrity_policy.stylesheet.enabled: 2
  safari
    <select> showPicker() method: 1
    CSS font-variant-emoji property: 1
    Canvas Filters: 1
    Cookie Store API CookieStoreManager: 4
    LinkPrefetch: 1
    Shape Detection API: 4
    SpeculationRules prefetch: 15
    referenceTarget: 4
    referenceTarget support for aria-owns: 4
    requestIdleCallback: 5
  safari_ios
    Contact Picker API: 4
runtime_flag
  chrome
    --enable-blink-features=ExperimentalProductivityFeatures: 2
  deno
    --location [url]: 15
    --unsafe-proto: 1
    --unstable-net: 44
    --unstable-node-globals: 1
    --unstable-unsafe-proto: 1
    --unstable-webgpu: 203
  nodejs
    --inspect: 4

All runtime flags start with -, and no preference starts with -.

[caugner]

I'd like to return to the idea of allowlisting flag names in the browser .json files, so other consumers can benefit too.

I don't think BCD should publish list of browser flags/runtime flags, but I could imagine creating a browser-flag-inventory package (like mdn-content-inventory) outside of the MDN org.

[Elchi3]

OK, it seems like more discussion is needed about flags. I'm glad there is an appetite to do more work on them.

For this PR, can we come to a decision, though? I scoped this PR just to get stable flag objects...

[caugner]

If we're open to allowing short-hands in the future (which simplifies manual and automated authoring, and increases readability by reducing noise), I don't have strong opinions about the ordering. Otherwise, the most important property (the name) should come first, which coincides with the alphabetical ordering (name, type, value_to_set).

The status quo is not necessarily intentional.

And if someone still wants a different sort, then they can advocate for it affirmatively in a follow up PR.

Surely once this PR has landed it will be almost impossible to convince you to change the ordering, if you're reluctant to make changes that introduce git history noise or that may cause merge conflicts.

Edit: I retract the above characterization. What I was trying, poorly, to express was a concern about the consequences of postponing the decision: after normalizing the repository to type-first, changing it later would produce the large diff/history noise that is currently an argument for retaining type-first. Doesn't that make postponing this decision somewhat self-reinforcing?

[ddbeck]

Surely once this PR has landed it will be almost impossible to convince you

@caugner What are you on about? This is out of line. A false accusation of intransigence is unprofessional and unwarranted.

I said that I liked the type-first order. I never said I was firmly committed to it. I characterized my own position as "bikeshedding." I called the small-diff approach the procedurally "right" choice (in sneer quotes!), informed by my experience with the migrations process of old, which is explicitly diff conscious.

I am not certain that type-first is the best option. I am open to other considerations. For example, we have not sought other contributors' input; I suspect Hamish and Chris have higher-than-average experience authoring this kind of data and might have valuable contributions to such a discussion.

In the absence of a quick and easy consensus, I earnestly wished to get something merged (for Florian to achieve the stability goal) and to let the the many threads here (sort order, build-time transformations, flag allowlists, etc.) to find their way to their own PRs and issues.

To close, I regret expressing my opinion here and bringing up extraneous issues. I am going to mark this PR approved, but otherwise withdraw from discussion here. You may sort it any which way you like.

[caugner]

What are you on about? This is out of line. A false accusation of intransigence is unprofessional and unwarranted.

Apologies. I sincerely regret my wording. I misinterpreted your reasoning and the intention behind your suggestion, and I should not have made that assumption about your position.

Let's land this order, even if it's not the one I consider preferable and Florian initially suggested. Then let me make the case for the shorthand in one of our next meetings.