Add ways to scope access to proposed API

[Tyriar]

We have a problem currently that if a first party wants to use one of our "forever proposed APIs" like window.onDidWriteTerminalData, they need to be added to our enable proposed API list which could lead them to accidentally use other proposed API which is likely to change.

This proposal is about adding a new API type which is stable but not accessible to anyone but close friends because of various concerns we have in making the API public. This would help these trusted parties not accidentally jump on proposed API and also help the general public from not trying out these APIs, I still get the occasional issue every now about someone who has tried onDidWriteTerminalData and asking about it being stabilized.

[jrieken]

This proposal is about adding a new API type which is stable but not accessible to anyone but close friends because of various concerns we have in making the API public.

I think this is how much of our proposed API is actually being used. I am not a fan of adding a third mechanism of restricted API or so. It will complicate things IMO.

[mjbvz]

One idea we previously discussed was a vscode.never.d.ts that tracks apis that we never plan on finalizing

[Tyriar]

Sure it will complicate things a little more on our side but it will save first party extensions from mistakenly using proposed API and breaking as a result. I can see how it would be tough to avoid this if your project includes vscode.proposed.d.ts.

[jrieken]

Sure it will complicate things a little more on our side but it will save first party extensions

This is not just about complexity but also about not being able to always cleanly separate things between N vscode.xyz.d.ts-files. We have seen that in the past and taken pragmatic approaches but that won't work for another stable/permanent d.ts-file.

This would help these trusted parties not accidentally jump on proposed API and also help the general public from not trying out these APIs

This reminds me of something that has been discussed previously - instead of giving extensions access to all proposed API they should have access to individual proposals only. This will help us manage the list extensions with access to proposed API and prevent accidental/unwanted API usage.

[Tyriar]

👍 opting into only a single API (or list) would fix the problem as well.

[jrieken]

(exploring ideas for september)

[jrieken]

Discussed a few ideas with @mjbvz. We have a couple of goals

• enable proposed API more fine grained
• clean-up the product.json files which today broadly list extensions that are allows to use proposed API
• don't introduce too much extra work on our side

This is the idea/plan

• each API proposal has an id, e.g the number of its track-issue as it's already used in region-comments
• enableProposedApi-property of package.json becomes a number-array instead of a boolean
• the checkProposedApiEnabled will be invoked with the corresponding proposal id

On the API implementation end we only need to invoke checkProposedApiEnabled with the right proposal id (tho that might be prone to copy-paste errors). Extensions need to spell out the proposals they are interested in. Listings in product.json can be updated when a proposal is finalized or removed

[gjsjohnmurray]

I like the proposal. Maybe also add telemetry on which proposed APIs are getting enabled. I'm hoping this would provide evidence to get some stalled ones finalized (see #59921 and #73524 for example, though those are the finalisation numbers, not the API ones). 🙏

[jrieken]

Moving out for actual implementation

[mjbvz]

@jrieken and I talked about this a little more. Here are some thoughts on the steps forward for this:

• Add logging and telemetry around proposed API usage (similar to what we do for deprecated apis).

• Reach out to all extensions that are using proposed API to learn which proposals they are currently using (if any)

• Add infrastructure in VS Code that limits an extension to a list of api proposals (either identified by issue number or with a unique name. Names a probably better since they will be more clear)

  Trying to use a proposed API not on your extension's allow list would result in an runtime error

• Initially let extensions access all proposed apis. As we hear back from extension maintainers, migrate our list of proposed api enabled extensions to list the specific set of proposals each extension needs

• After a few months, hopefully we will have updated all extensions to list just the proposals they need

[jrieken]

Plan of action

1. break up vscode.proposed.d.ts into a file per proposal, like vscode.proposed.languageStatus.d.ts and vscode.proposed.remoteResolver.d.ts (Note that proposals use names instead of numbers)
2. change the enableProposedApi-property to be a list of proposal names. For a grace period interpret true as "all proposal names".
3. adjust our checkProposedApiEnabled-checks to accept a proposal name
4. update the vscode-dts command line tool to fetch individual proposals
5. add tooling to generate a list of proposal names (similar to how we generate monaco.d.ts). This will help to type-check checkProposedApiEnabled-calls and to provide good JSON-schema for enableProposedAPI

---

1. update vsce check for enable proposed API
2. reach out to extensions listed in product.json#enableProposedApi to spell out the proposals they depend on

[jrieken]

Pushed 799d82f to ensure checkProposedApiEnabled and (new) isProposedApiEnabled utils are used

[jrieken]

Merged the removal of enableProposedApi - it is all enabledApiProposals from now on but extensions listed in product.json are still treated special

[CodeCasterNL]

@jrieken documentation like Inline Completions Sample still links to the old file locations (a4d426a).

[jrieken]

/cc @hediet ⬆️

[GusSand]

There's a bunch of things that seem to need to change in the samples that reference the new API:

Documentation - already mentioned
package.json - how to modify it to add the proposed API
post install script - needs to be updated to download the correct file.
thanks!