Add virtual workspace support section

release-notes/v1_56.md

@@ -354,6 +354,25 @@ You can learn about new extension features and bug fixes in the [Remote Developm
 
 ## Extension authoring
 
+### Define whether your extension supports a virtual workspace
+
+The [FileSystemProvider API](https://github.com/microsoft/vscode/blob/dc8bd9cd7e5231745549ac6218266c63271f48cd/src/vs/vscode.d.ts#L7038) enables extensions to serve files from remote places, like ftp-servers, and to seamlessly provide these files to the user in VS Code. This feature has existed since a while. However, we have observed that not all extensions can support running in a __virtual workspace__ where the workspace files do not exist physically on disk. For this reason we have added support for an extension to opt-out of running in a virtual workspace. When an extension has opted-out, then it will not be activated by VS Code for a virtual workspace and the user will not see errors from this extension.
+
+An extension opts out of a virtual workspace setup in the `package.json` as shown below:
+
+```json
+  "capabilities": {
+    "virtualWorkspaces": false
+  }
+}
+```
+
+The default value of the `virtualWorkspaces` property is `true`. The goal is that as many extensions as possible support a virtual workspace setup. However, this is not always possible. In particular, when an extension is using components that assume that files are physically present.  This [guide](https://github.com/microsoft/vscode/wiki/Virtual-Workspaces) documents how an extension can support a virtual workspace.
+
+There will be a transition period until extensions have adopted the new `virtualWorkspaces` property. To help with the transition we maintain an internal list for extensions that we think should have the `virtualWorkspaces` capability set to `false`. This was done based on an analysis whether the extensions is using the node `fs` module and is therefore accessing the file system directly. However, the extension author is in a much better position to assess whether an extension supports the `virtualWorkspaces` capability. To track the adoption we have created the following [tracking issue](https://github.com/microsoft/vscode/issues/122836).
+
+**Call to Action**: Please check whether your extension is included in the [list of extensions](https://github.com/microsoft/vscode/issues/122836) for which `virtualWorkspaces` is set to `false` by VS Code. If you have reviewed whether your extension supports virtual workspaces and you have updated the `virtualWorkspaces` property in the `package.json`, then please add a comment in the above issue. If your extension is not in the list then please review whether your extension should have the `virtualWorkspaces` capability set to false. In both cases use the [Virtual Workspaces Guide](https://github.com/microsoft/vscode/wiki/Virtual-Workspaces) for guidance.
+
 ### iframes now used for most webviews
 
 Ever since the webview API was first introduced, we've implemented webview using [Electron's `<webview>` tag](https://www.electronjs.org/docs/api/webview-tag). On the web however, VS Code's webviews are instead implemented using standard `<iframe>` elements since `<webview>` is not available.