VS Code API support: proposed APIs

[paul-marechal]

We're currently tracking support for the official VS Code API for a given target version but this excludes proposed APIs.

Proposed APIs are important for VS Code builtins: These are extensions developed directly alongside VS Code and while they mostly use the official VS Code API they also make use of some proposed APIs (most likely for dogfooding).

The tricky part about proposed APIs is that it is a variable set, with no guarantee made for backward compatibility. Unlike the official VS Code API which is only ever growing without changing previous APIs in breaking ways, the proposed API set may vary and break across VS Code versions. Breakage may not happen often but it may happen which means we need to handle this carefully.

The approach we came up with would be to:

1. Look at the current VS Code API version we target in the framework.
2. List all the proposed APIs used by builtins for this version.
3. Track the implementation/stubbing of these APIs alongside the rest of the tracked stable VS Code APIs.
4. Repeat previous steps for every new target VS Code API version.

Doing this would mean we could release builtins for Theia's target VS Code API version and have them work. If applications makers were to use builtins built for a different version than the target version then there's good chances that it will work but there's also chances that it will not work/behave in weird ways because of incompatible proposed APIs expectation and implementation. This would be a known issue and the fix would be to use a builtin built for the right target version.

Builtins contribute important features such as TypeScript support, Git support, and more. Better supporting the infrastructure required for them to function is then equally important in our opinion.

Any thoughts about this? What about the proposed process? Ok to track proposed APIs alongside stable ones when moving to support new VS Code versions?

[JonasHelming]

@rschnekenbu : Could you look at this and discuss with me

[tsmaeder]

Using proposed API in release version does not only seem to be a problem in built-ins: https://github.com/Microsoft/vscode-jupyter, for example seems to use onDidChangeNotebookCellExecutionState, which is proposed API.

[tsmaeder]

I was wondering how we would actually structure the code for proposed API: I would suggest we move to the same organization as VS Code has now, where there is a separate file per proposal.

[rschnekenbu]

AFAIK, there are currently 2 ways to check for the extensions support: 

• the script that analyzes the used proposed APIs for the built-ins (see https://github.com/eclipse-theia/vscode-builtin-extensions/wiki/Produce-and-Publish-the-set-of-vscode-built-in-extensions#proposed-api-in-theia). This report displays for each extension which proposed API file it is currently using. It does not check the content of the file however (which type is used).
• the vscodecov tool. vscodecov evaluates the used APIs, and as such, it could be improved to detect the missing APIs from the proposed ones. I have tested this tool on vscode-jupyter. vscodecov still has some issues. It reports for example false positives, as inherited members (bug: Support inheritance theia-vscodecov#6) which should be quite simple to address if we go this way. The report allows however some good findings, as the missing proposed APIs :
  Full report for release vscode-jupyter 2022.10.110
  excerpt from the vscodecov report:

"missingSymbols": [
[...]
    "\"vscode\".NotebookCellOutput.id",
    "\"vscode\".NotebookController.asWebviewUri", 
    "\"vscode\".NotebookController.kind",
 [...]
    "\"vscode\".extensions.onDidChange",
    "\"vscode\".notebooks.onDidChangeNotebookCellExecutionState",
    "\"vscode\".workspace.registerPortAttributesProvider"
  ],
[...]

Note:

• ""vscode".NotebookController.asWebviewUri" comes from vscode.proposed.notebookMessaging.d.ts
• ""vscode".notebooks.onDidChangeNotebookCellExecutionState" comes from vscode.proposed.notebookCellExecutionState.d.ts

I would suggest for a better support to automate this reporting. For example, for each or all of the built-ins, we should detect which proposed / public APIs we are currently supporting by implementing or stubbing them, as done for the current theia vscode report.

It would be nice to get this report for any given version of theia and vscode, from a local repo or from github.
The report shall provide a table as done for the public API. It should also add the source file containing the proposed API, as proposed APIs are currently shipped in different files as mentioned earlier by Thomas.

For the process, we shall ensure before bumping the API support that we are currently on par with both public APIs and proposed APIs.
The API tracking task shall then propose for each version:

• subtask(s) for the added APIs for a given version
• subtask(s) for the added / removed / changed APIs for the proposed APIs
• subtask to update builtins?
• subtask to bump API