enableProposedApi not documented in package.json

[isidorn]

Refs: #33248

enableProposedApi is not suggested in package.json inteli-sense
Due to that it is hard to discover this flag. Is this on purpose?

[jrieken]

Yeah, that is actually on purpose because we don't want to over-promote this. Still, we should document somewhere how proposed API to be used

[aeschli]

IMO we should add it. The description can explain the limitations you get when you use it. Given the limitations, there's IMO no danger that too many devs will use it.

[octref]

@jrieken Can we include it in a section under Extensibility Reference in the website? I don't want to go into GitHub comments to find out the instruction for using proposed API each time. If that's fine, I can create a placeholder page in the website and you can fill in details.

Alternatively, as @rcjsuen suggested, put the instruction to the top of vscode.proposed.d.ts.

[octref]

I added

• Documentation: https://vscode-ext-docs.azurewebsites.net/api/advanced-topics/using-proposed-api
• Sample: https://github.com/Microsoft/vscode-extension-samples/tree/ext-docs/proposed-api-sample

@jrieken Please verify the docs and sample, and edit as you see fit.

[jrieken]

👍 for the documentation and 👎 for the sample. That will be out of date in no-time and I also don't think that it adds value

[octref]

@jrieken However, currently it's awkward to update your code to use Proposed API. Each time I had to remember to do this:

• Find latest vscode.d.ts
• Change vscode.engines to *
• Run postinstall scripts to download latest d.ts
• Change vscode.engines back
• Remember to add enabledProposedApi to package.json. I sometimes type it wrongly as API and nothing works.

If sample is not the right place, what do you think about adding another script to the vscode NPM module to automate this? So people can run node ./node_modules/vscode/use-proposed-api. We can print warnings and have confirmations here too.

[jrieken]

@octref step 1 to 4 have nothing to do with proposed api. that's the procedure when coding against the latest, not yet published, version of vscode.d.ts and is only rarely needed.

for proposed API the three steps outline here are needed: https://code.visualstudio.com/updates/v1_28#_proposed-extension-apis

[octref]

OK I'll drop the sample.

[mjbvz]

Should this issue be reopened or marked as wont-fix?

[octref]

To verify:

• Verify the content https://vscode-ext-docs.azurewebsites.net/api/advanced-topics/using-proposed-api makes sense to you.
• Verify the top comment in vscode.proposed.d.ts makes sense to you.