Merge branch 'main' into vnext

Author: gregvanl

README.md

@@ -9,6 +9,8 @@ Topics submitted here will be published to the [Visual Studio Code](https://code
 
 If you are looking for the VS Code product GitHub repository, you can find it [here](https://github.com/microsoft/vscode).
 
+>**Note**: The vscode-docs repository uses [Git LFS](https://git-lfs.github.com/) (Large File Storage) for storing binary files such as images and `.gif`s. If you are contributing or updating images, please enable Git LFS per the instructions in the [Contributing](#cloning) section below.
+
 ## Index
 
 - [Index](#index)

api/advanced-topics/remote-extensions.md

@@ -202,6 +202,12 @@ export function activate(context: vscode.ExtensionContext) {
 }
 ```
 
+### Sync user global state between machines
+
+If your extension needs to preserve some user state across different machines then provide the state to [Settings Sync](/docs/editor/settings-sync) using `vscode.ExtensionContext.globalState.setKeysForSync`. This can help prevent displaying the same welcome or updates page to users on multiple machines.
+
+There is an example of using `setKeysforSync` in the [Extension Capabilities](/api/extension-capabilities/common-capabilities#data-storage) topic.
+
 ### Persisting secrets
 
 If your extension needs to persist passwords or other secrets, you may want to use your local operating system's secret store (Windows Cert Store, the macOS KeyChain, a `libsecret`-based keyring on Linux, or a browser-based equivalent) rather than the one on the remote machine environment. Further, on Linux you may be relying on `libsecret` and by extension `gnome-keyring` to store your secrets, and this does not typically work well on server distros or in a container.

api/extension-capabilities/common-capabilities.md

@@ -45,6 +45,29 @@ There are four options for storing data:
 
 The extension context is available to the `activate` function in the [Extension Entry File](/api/get-started/extension-anatomy#extension-entry-file).
 
+### setKeysForSync example
+
+If your extension needs to preserve some user state across different machines then provide the state to [Setting Sync](/docs/editor/settings-sync) using `vscode.ExtensionContext.globalState.setKeysForSync`.
+
+You can use the following pattern:
+
+```TypeScript
+// on activate
+const versionKey = context.extension.id + '.version';
+context.globalState.setKeysForSync([versionKey]);
+
+// later on show page
+const currentVersion = context.extension.packageJSON.version;
+const lastVersionShown = context.globalState.get(versionKey);
+if (!isHigher(currentVersion, lastVersionShown)) {
+    return;
+}
+context.globalState.set(versionKey, currentVersion);
+// show page
+```
+
+Sharing state across machines can help avoid the problem of users seeing multiple instances of a welcome or update page, by sharing dismissed or viewed flags.
+
 ## Display Notifications
 
 Almost all extensions need to present information to the user at some point. VS Code offers three APIs for displaying notification messages of different severity:

api/extension-guides/file-icon-theme.md

@@ -65,7 +65,7 @@ The following properties are supported:
 
 ### File association
 
-Icons can be associated to folders, folder names, files, file extensions, file names and [language ids](/api/references/contribution-points#contributes.languages).
+Icons can be associated to folders, folder names, files, file extensions, file names and [language IDs](/api/references/contribution-points#contributes.languages).
 
 Additionally each of these associations can be refined for 'light' and 'highContrast' color themes.
 
@@ -100,17 +100,17 @@ Each file association points to an icon definition.
 }
 ```
 
-- `file` is the default file icon, shown for all files that don't match any extension, filename or language id. Currently all properties defined by the definition of the file icon will be inherited (only relevant for font glyphs, useful for the fontSize).
+- `file` is the default file icon, shown for all files that don't match any extension, filename or language ID. Currently all properties defined by the definition of the file icon will be inherited (only relevant for font glyphs, useful for the fontSize).
 - `folder` is the folder icon for collapsed folders, and if `folderExpanded` is not set, also for expanded folders. Icons for specific folder names can be associated using the `folderNames` property.
   The folder icon is optional. If not set, no icon will be shown for folder.
 - `folderExpanded` is the folder icon for expanded folders. The expanded folder icon is optional. If not set, the icon defined for `folder` will be shown.
 - `folderNames` associates folder names to icons. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive.
 - `folderNamesExpanded` associates folder names to icons for expanded folder. The key of the set is the folder name, not including any path segments. Patterns or wildcards are not supported. Folder name matching is case insensitive.
 - `rootFolder` is the folder icon for collapsed workspace root folders , and if `rootFolderExpanded` is not set, also for expanded workspace root folders. If not set, the icon defined for `folder` will be shown for workspace root folders.
-- `rootFolderExpanded` is the folder icon for expanded workspace root folders. If not set, the icon defined for `rootFolder` will be shown for exanded workspace root folders.
-- `languageIds` associates languages to icons. The key in the set is the language id as defined in the [language contribution point](/api/references/contribution-points#contributes.languages). The language of a file is evaluated based on the file extensions and file names as defined in the language contribution. Note that the 'first line match' of the language contribution is not considered.
+- `rootFolderExpanded` is the folder icon for expanded workspace root folders. If not set, the icon defined for `rootFolder` will be shown for expanded workspace root folders.
+- `languageIds` associates languages to icons. The key in the set is the language ID as defined in the [language contribution point](/api/references/contribution-points#contributes.languages). The language of a file is evaluated based on the file extensions and file names as defined in the language contribution. Note that the 'first line match' of the language contribution is not considered.
 - `fileExtensions` associates file extensions to icons. The key in the set is the file extension name. The extension name is a file name segment after a dot (not including the dot). File names with multiple dots such as `lib.d.ts` can match multiple extensions; 'd.ts' and 'ts'. Extensions are compared case insensitive.
-- `fileNames` associates file names to icons. The key in the set is the full file name, not including any path segments. Patterns or wildcards are not supported. File name matching is case insensitive. A 'fileName' match is the strongest match, and the icon associated to the file name will be preferred over an icon of a matching fileExtension and also of a matching language Id.
+- `fileNames` associates file names to icons. The key in the set is the full file name, not including any path segments. Patterns or wildcards are not supported. File name matching is case insensitive. A 'fileName' match is the strongest match, and the icon associated to the file name will be preferred over an icon of a matching fileExtension and also of a matching language ID.
 
 A file extension match is preferred over a language match, but is weaker than a file name match.
 

api/extension-guides/testing.md

@@ -1,4 +1,8 @@
 ---
+# DO NOT TOUCH — Managed by doc writer
+ContentId: 4ced0b2a-3f5a-44e6-a8b0-66b9012af8c0
+DateApproved: 8/5/2021
+
 # Summarize the whole topic in less than 300 characters for SEO purpose
 MetaDescription: Testing APIs in VS Code allow users to discover and run unit tests in their workspace
 ---
@@ -7,6 +11,8 @@ MetaDescription: Testing APIs in VS Code allow users to discover and run unit te
 
 The Testing API allows Visual Studio Code extensions to discover tests in the workspace and publish results. Users can execute tests in the Test Explorer view, from decorations, and inside commands. With these new APIs, Visual Studio Code supports richer displays of outputs and diffs than was previously possible.
 
+>**Note**: The Testing API is available in VS Code version 1.59 and higher.
+
 ## Examples
 
 There are two test providers maintained by the VS Code team:
@@ -22,7 +28,7 @@ Tests are provided by the `TestController`, which requires a globally unique ID
 const controller = vscode.tests.createTestController('helloWorldTests', 'Hello World Tests');
 ```
 
-To publish tests, you add `TestITem`s as children to the controller's `items` collection. `TestItem`s are the foundation of the test API in the `TestItem` interface, and are a generic type that can describe a test case, suite, or tree item as it exists in code. They can, in turn, have `children` themselves, forming a hierarchy. For example, here's a simplified version of how the sample test extension creates tests:
+To publish tests, you add `TestItem`s as children to the controller's `items` collection. `TestItem`s are the foundation of the test API in the `TestItem` interface, and are a generic type that can describe a test case, suite, or tree item as it exists in code. They can, in turn, have `children` themselves, forming a hierarchy. For example, here's a simplified version of how the sample test extension creates tests:
 
 ```ts
 parseMarkdown(content, {
@@ -275,3 +281,11 @@ In summary, the general steps are:
 1. To load tests initially, instead of waiting for a `testAdapter.load()` method call, set `controller.resolveHandler = () => { /* discover tests */ }`. See more information around how test discovery works in [Discovering Tests](#discovering-tests).
 
 1. To run tests, you should create a [Run Profile](#running-tests) with a handler function that calls `const run = controller.createTestRun(request)`. Instead of firing a `testStates` event, pass `TestItem`s to methods on the `run` to update their state.
+
+## Additional Contribution Points
+
+The `testing/item/context` [menu contribution point](/api/references/contribution-points#contributes.menus) may be used to add menu items to Tests in the Test Explorer view. Place menu items in the `inline` group to have them inline. All other menu item groups will be represented in a context menu usually accessible using the mouse right-click.
+
+Additional [context keys](/api/references/when-clause-contexts) are available in the `when` clauses of your menu items: `testId`, `controllerId`, and `testItemHasUri`. For more complex `when` scenarios where you want actions to be optionally available for different Test Items, consider using the [`in` conditional operator](/api/references/when-clause-contexts#in-conditional-operator).
+
+If want to reveal a test in the explorer, you can pass it running the command `vscode.commands.runCommand('vscode.revealTestInExplorer', testId)`.

api/get-started/extension-anatomy.md

@@ -13,9 +13,9 @@ In the last topic, you were able to get a basic extension running. How does it w
 
 The `Hello World` extension does 3 things:
 
-- Registers the [`onCommand`](/api/references/activation-events#onCommand) [**Activation Event**](/api/references/activation-events): `onCommand:extension.helloWorld`, so the extension becomes activated when user runs the `Hello World` command.
-- Uses the [`contributes.commands`](/api/references/contribution-points#contributes.commands) [**Contribution Point**](/api/references/contribution-points) to make the command `Hello World` available in the Command Palette, and bind it to a command ID `extension.helloWorld`.
-- Uses the [`commands.registerCommand`](/api/references/vscode-api#commands.registerCommand) [**VS Code API**](/api/references/vscode-api) to bind a function to the registered command ID `extension.helloWorld`.
+- Registers the [`onCommand`](/api/references/activation-events#onCommand) [**Activation Event**](/api/references/activation-events): `onCommand:helloworld.helloWorld`, so the extension becomes activated when user runs the `Hello World` command.
+- Uses the [`contributes.commands`](/api/references/contribution-points#contributes.commands) [**Contribution Point**](/api/references/contribution-points) to make the command `Hello World` available in the Command Palette, and bind it to a command ID `helloworld.helloWorld`.
+- Uses the [`commands.registerCommand`](/api/references/vscode-api#commands.registerCommand) [**VS Code API**](/api/references/vscode-api) to bind a function to the registered command ID `helloworld.helloWorld`.
 
 Understanding these three concepts is crucial to writing extensions in VS Code:
 
@@ -71,12 +71,12 @@ Each VS Code extension must have a `package.json` as its [Extension Manifest](/a
     "vscode": "^1.51.0"
   },
   "categories": ["Other"],
-  "activationEvents": ["onCommand:extension.helloWorld"],
+  "activationEvents": ["onCommand:helloworld.helloWorld"],
   "main": "./out/extension.js",
   "contributes": {
     "commands": [
       {
-        "command": "extension.helloWorld",
+        "command": "helloworld.helloWorld",
         "title": "Hello World"
       }
     ]
@@ -116,7 +116,7 @@ export function activate(context: vscode.ExtensionContext) {
   // The command has been defined in the package.json file
   // Now provide the implementation of the command with registerCommand
   // The commandId parameter must match the command field in package.json
-  let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
+  let disposable = vscode.commands.registerCommand('helloworld.helloWorld', () => {
     // The code you place here will be executed every time your command is executed
 
     // Display a message box to the user

api/language-extensions/syntax-highlight-guide.md

@@ -180,9 +180,9 @@ To quickly create a new grammar extension, use [VS Code's Yeoman templates](/api
 
 Yeoman will walk you through some basic questions to scaffold the new extension. The important questions for creating a new grammar are:
 
-- `Language Id` - A unique identifier for your language.
-- `Language Name` - A human readable name for your language.
-- `Scope names` - Root TextMate scope name for your grammar
+- `Language id` - A unique identifier for your language.
+- `Language name` - A human readable name for your language.
+- `Scope names` - Root TextMate scope name for your grammar.
 
 ![Filling in the 'new language' questions](images/syntax-highlighting/yo-new-language-questions.png)
 

api/references/contribution-points.md

@@ -708,6 +708,7 @@ Currently extension writers can contribute to:
 - The Timeline view title menu bar - `timeline/title`
 - The Timeline view item context menu - `timeline/item/context`
 - The Extensions view context menu - `extension/context`
+- The Test Explorer item context menu - `testing/item/context`
 - Any [contributed submenu](/api/references/contribution-points#contributes.submenus)
 
 > **Note:** When a command is invoked from a (context) menu, VS Code tries to infer the currently selected resource and passes that as a parameter when invoking the command. For instance, a menu item inside the Explorer is passed the URI of the selected resource and a menu item inside an editor is passed the URI of the document.

api/references/extension-manifest.md

@@ -55,7 +55,7 @@ Here is a complete `package.json`
   "publisher": "ms-vscode",
   "description": "Markdown Word Count Example - reports out the number of words in a Markdown file.",
   "author": {
-    "name": "seanmcbreen"
+    "name": "sean"
   },
   "categories": ["Other"],
   "icon": "images/icon.png",
@@ -79,7 +79,7 @@ Here is a complete `package.json`
   "license": "SEE LICENSE IN LICENSE.txt",
   "bugs": {
     "url": "https://github.com/microsoft/vscode-wordcount/issues",
-    "email": "smcbreen@microsoft.com"
+    "email": "sean@contoso.com"
   },
   "repository": {
     "type": "git",
@@ -129,7 +129,7 @@ There are several optional links (`bugs`, `homepage`, `repository`) you can set
   "homepage": "https://github.com/microsoft/vscode-wordcount/blob/main/README.md",
   "bugs": {
     "url": "https://github.com/microsoft/vscode-wordcount/issues",
-    "email": "smcbreen@microsoft.com"
+    "email": "sean@contoso.com"
   },
   "repository": {
     "type": "git",

api/references/vscode-api.md

@@ -802,7 +802,7 @@ mouse, positioning the hover, keeping the hover stable etc. is taken care of by
     }
 });
 </code></pre>
-<p>Registration is done using a <a href="#DocumentSelector">document selector</a> which is either a language id, like <code>javascript</code> or
+<p>Registration is done using a <a href="#DocumentSelector">document selector</a> which is either a language ID, like <code>javascript</code> or
 a more complex <a href="#DocumentFilter">filter</a> like <code>{ language: &#39;typescript&#39;, scheme: &#39;file&#39; }</code>. Matching a document against such
 a selector will result in a <a href="#languages.match">score</a> that is used to determine if and how a provider shall be used. When
 scores are equal the provider that came last wins. For features that allow full arity, like <a href="#languages.registerHoverProvider">hover</a>,
@@ -3031,7 +3031,7 @@ when the <a href="#TextDocument.getText">contents</a> changes but also when othe
 
 <a name="workspace.onDidCloseTextDocument"></a><span class="ts" id=2970 data-target="#details-2970" data-toggle="collapse"><span class="ident">onDidCloseTextDocument</span><span>: </span><a class="type-ref" href="#Event">Event</a>&lt;<a class="type-ref" href="#TextDocument">TextDocument</a>&gt;</span>
 <div class="details collapse" id="details-2970">
-<div class="comment"><p>An event that is emitted when a <a href="#TextDocument">text document</a> is disposed or when the language id
+<div class="comment"><p>An event that is emitted when a <a href="#TextDocument">text document</a> is disposed or when the language ID
 of a text document <a href="#languages.setTextDocumentLanguage">has been changed</a>.</p>
 <p><em>Note 1:</em> There is no guarantee that this event fires when an editor tab is closed, use the
 <a href="#window.onDidChangeVisibleTextEditors"><code>onDidChangeVisibleTextEditors</code></a>-event to know when editors change.</p>
@@ -3069,7 +3069,7 @@ files change on disk, e.g triggered by another application, or when using the
 
 <a name="workspace.onDidOpenTextDocument"></a><span class="ts" id=2969 data-target="#details-2969" data-toggle="collapse"><span class="ident">onDidOpenTextDocument</span><span>: </span><a class="type-ref" href="#Event">Event</a>&lt;<a class="type-ref" href="#TextDocument">TextDocument</a>&gt;</span>
 <div class="details collapse" id="details-2969">
-<div class="comment"><p>An event that is emitted when a <a href="#TextDocument">text document</a> is opened or when the language id
+<div class="comment"><p>An event that is emitted when a <a href="#TextDocument">text document</a> is opened or when the language ID
 of a text document <a href="#languages.setTextDocumentLanguage">has been changed</a>.</p>
 <p>To add an event listener when a visible text document is opened, use the <a href="#TextEditor">TextEditor</a> events in the
 <a href="#window">window</a> namespace. Note that:</p>
@@ -8566,7 +8566,7 @@ its resource, or a glob-pattern that is applied to the <a href="#TextDocument.fi
 
 <a name="DocumentFilter.language"></a><span class="ts" id=557 data-target="#details-557" data-toggle="collapse"><span class="ident">language</span><span>?</span><span>: </span><a class="type-intrinsic">string</a></span>
 <div class="details collapse" id="details-557">
-<div class="comment"><p>A language id, like <code>typescript</code>.</p>
+<div class="comment"><p>A language ID, like <code>typescript</code>.</p>
 </div>
 </div>
 
@@ -20907,7 +20907,7 @@ const values = config.get(&#39;configurations&#39;);
 often consists of a <em>default</em> value, a global or installation-wide value,
 a workspace-specific value, folder-specific value
 and language-specific values (if <a href="#WorkspaceConfiguration">WorkspaceConfiguration</a> is scoped to a language).</p>
-<p>Also provides all language ids under which the given configuration setting is defined.</p>
+<p>Also provides all language IDs under which the given configuration setting is defined.</p>
 <p><em>Note:</em> The configuration name must denote a leaf in the configuration tree
 (<code>editor.fontSize</code> vs <code>editor</code>) otherwise no result is returned.</p>
 </div>