Withhold origin trial features from API Reference generation

[jpmedley]

The API reference displays items that are in origin trials without indicating them as such. This has a number of problems.

• The existence of an origin trial is no guarantee of shipping. In eight years, I've seen features that were shipped with a different API surface, I've seen features that went through a second origin trial with a different design, and I've seen features that did not ship at all.
• Because this feature is only available in an origin trial, extension developers can't count on its availability. To even use it, host sites must have opt-in to the origin trial. In the most optimistic case, this feature is only available to 1 web site in every 1.5 million.
• Our documentation gives no indication that this is experimental, much less how I could test it if I wanted to.
• We do not publicize origin trials that affect extensions and provide no general guidance for how an extension developer can participate in an origin trial.
• Do we even want extension developer participating in origin trials?

For example, so that extensions can handle Back/Forward (sic) caching a few things have been added to extension APIs. One of them is called FrameType. One of the values of FrameType is "fenced_frame". But Fenced Frame is in an origin trial that finished by the time Chrome shipped 108 on November 29.

This issue is a request to either hide or correctly label items that are in origin trials. I favor hiding since labeling such items requires additional documentation and publicity that may or may not be useful to our developers.

Regardless of which option we chose, the first step will be making the conversion process aware of origin trials.

[jpmedley]

cc: @dotproto @ali-spivak

[dotproto]

cc: @rdcronin

[dotproto]

Just chatted with Devlin about this. At the moment, I think it makes sense for documentation to reflect that certain capabilities related to origin trials are exposed, but we shouldn't completely omit them. There are a couple of relevant factors here:

Lower level brower concepts – Extensions can integrate very deeply with browser implementation details in order to do what they do. Not all extensions will need to handle features like the "fenced_frame" FrameType, but the ones that do do.

Trials for thee but not for me – If a website opts into a trial that overlaps with extensions APIs, that opt-in only affects their website and no others. But extensions span all websites a user visits. That overlapping trial can lead to buggy behavior in the extension and that could be a critical problem for the extension.

Overlap is (relatively) uncommon – Origin trials and extensions capabilities don't often overlap. In the past 5 years the only 2 cases I can think of right now are MPArch (bfcache & related work) and fenced frames. That said, fenced frames are related to Google's Privacy Sandbox effort and due to how closely that effort ties into web platform primitives there may be more overlap in the future.

At the moment I think the most practical course is to add a callout about (and link to) the origin trial to the API docs in Chromium source as appropriate and give ourselves follow-up issues for future milestones to check if the callout is still necessary/accurate.

We should keep an eye on how frequently we encounter origin trial-related extension doc concerns and the related maintenance cost of these efforts. If the maintenance burden gets high enough (or the engineering cost gets low enough), we can revisit this approach and discuss automating the process.

[jpmedley]

Simeon,

Thank you for following up. This all sounds good except for one thing.

"If the maintenance burden gets high enough (or the engineering cost gets

low enough), we can revisit this approach and discuss automating the process."

The cost of putting something ephemeral in stable documentation is low, but that's not the cost we should be concerned about. The chances of remembering to remove ephemeral bits of information are low and when teams do remember to remove them, the chances of finding everything that needs to be removed are also low. Over time, this results in the build up of irrelevant and outdated cruft that gives the impression we're neglecting documentation.

I am investigating other approaches to this problem. I would like to keep automation on the backlog until we can at least figure out if it is easy or difficult to implement. Joe Medley | Technical Writer, Chrome DevRel | @.** | 816-678-7195 If an API's not documented it doesn't exist.*

On Thu, Dec 1, 2022 at 6:19 PM Simeon Vincent @.***> wrote:

Just chatted with Devlin about this. At the moment, I think it makes sense for documentation to reflect that certain capabilities related to origin trials are exposed, but we shouldn't completely omit them. There are a couple of relevant factors here:

Lower level brower concepts – Extensions can integrate very deeply with browser implementation details in order to do what they do. Not all extensions will need to handle features like the "fenced_frame" FrameType, but the ones that do do.

Trials for thee but not for me – If a website opts into a trial that overlaps with extensions APIs, that opt-in only affects their website and no others. But extensions span all websites a user visits. That overlapping trial can lead to buggy behavior in the extension and that could be a critical problem for the extension.

Overlap is (relatively) uncommon – Origin trials and extensions capabilities don't often overlap. In the past 5 years the only 2 cases I can think of right now are MPArch https://blogs.igalia.com/gyuyoung/2022/10/13/mparchmultiple-page-architecture-project-in-chromium/ (bfcache https://web.dev/bfcache/ & related work) and fenced frames. That said, fenced frames are related to Google's Privacy Sandbox effort and due to how closely that effort ties into web platform primitives there may be more overlap in the future.

At the moment I think the most practical course is to add a callout about (and link to) the origin trial to the API docs in Chromium source as appropriate and give ourselves follow-up issues for future milestones to check if the callout is still necessary/accurate.

We should keep an eye on how frequently we encounter origin trial-related extension doc concerns and the related maintenance cost of these efforts. If the maintenance burden gets high enough (or the engineering cost gets low enough), we can revisit this approach and discuss automating the process.

— Reply to this email directly, view it on GitHub https://github.com/GoogleChrome/chrome-types/issues/42#issuecomment-1334680243, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB6S7C2T33L46IPWOEMK7W3WLFMBLANCNFSM6AAAAAASO26E7E . You are receiving this because you authored the thread.Message ID: @.***>