From 5dcecfd2daa29feda73aa00ebe0a89357254f26c Mon Sep 17 00:00:00 2001 From: Kasper Davidsen Date: Sat, 19 Feb 2022 17:23:27 +0100 Subject: [PATCH 01/46] Add documentation for projectName on compose tasks --- docs/containers/reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/containers/reference.md b/docs/containers/reference.md index 6942251560..c69e2c67ef 100644 --- a/docs/containers/reference.md +++ b/docs/containers/reference.md @@ -444,6 +444,7 @@ Here are all properties available for configuring `docker-compose` task. All pro | `down` | Run a `docker-compose down` command.
Either this or `up` must be specified, but not both. | `docker-compose down` | | `files` | The list of Docker Compose YAML files to use in the `docker-compose` command. If not specified, the Docker Compose CLI looks for `docker-compose.yml` and `docker-compose.override.yml`. | `-f ` | | `envFile` | File of environment variables read in and applied to the containers. | `--env-file ` | +| `projectName` | Alternate project name to use when naming and labeling Docker objects. If using an alternate project name when composing up, the same project name must be specified when composing down. | `--project-name ` | ### up object properties From 8191287b44d9f25d257ceffae3ee6f90611850f6 Mon Sep 17 00:00:00 2001 From: Esteban Dalel R Date: Fri, 4 Mar 2022 11:29:30 -0600 Subject: [PATCH 02/46] Update continuous-integration.md Github now sets the default branch as "main", set it for automated deploys too. --- api/working-with-extensions/continuous-integration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/working-with-extensions/continuous-integration.md b/api/working-with-extensions/continuous-integration.md index 02bbdd1715..6d7a764fa0 100644 --- a/api/working-with-extensions/continuous-integration.md +++ b/api/working-with-extensions/continuous-integration.md @@ -31,7 +31,7 @@ Then, add the following `azure-pipelines.yml` file to the root of your extension trigger: branches: include: - - master + - main tags: include: - v* @@ -97,7 +97,7 @@ You can enable the build to run continuously when pushing to a branch and even o trigger: branches: include: - - master + - main tags: include: - refs/tags/v* @@ -133,7 +133,7 @@ You can also configure GitHub Actions to run your extension CI. In headless Linu on: push: branches: - - master + - main jobs: build: @@ -173,7 +173,7 @@ jobs: on: push: branches: - - master + - main release: types: - created From 86a52c1df89997e64e0134f284cc10cb323f684e Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 4 Mar 2022 14:13:19 -0800 Subject: [PATCH 03/46] Update CLI doc --- docs/remote/devcontainer-cli.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/remote/devcontainer-cli.md b/docs/remote/devcontainer-cli.md index 0e7da0f435..f2d75bbf21 100644 --- a/docs/remote/devcontainer-cli.md +++ b/docs/remote/devcontainer-cli.md @@ -4,16 +4,23 @@ Area: remote TOCTitle: devcontainer CLI PageTitle: Installing and working with the devcontainer CLI ContentId: 8946213d-716e-41ca-955f-944a41c70353 -MetaDescription: Documentation on using the devcontainer command line interface with the Visual Studio Code Remote - Containers extension +MetaDescription: Documentation on using the VS Code devcontainer command line interface with the Visual Studio Code Remote - Containers extension DateApproved: 3/3/2022 --- -# devcontainer command line interface +# Development container command line interface +When we refer to a command line interface (CLI) for development containers, there are two varieties: +* "dev container CLI" - A reference implementation for the open dev container spec. The [current proposal](https://github.com/microsoft/dev-container-spec/issues/9) is to make a CLI available that can take a `devcontainer.json` and create and configure a dev container from it. It could be available in any IDE or editor. +* "Visual Studio Code `devcontainer` CLI" - A CLI that can be installed and used via the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or through an external terminal. -Given the growing number of use cases for dev containers, there is a companion `devcontainer` command line interface (CLI) that can be used independent of the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or GitHub Codespaces. This article will walk you through its installation and how to use it in different scenarios. +The former is in-progress. The latter is available today and the focus of this document. + +## Visual Studio Code `devcontainer` CLI + +Given the growing number of use cases for dev containers, there is a companion `devcontainer` CLI that can be used independent of the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or GitHub Codespaces. This article will walk you through its installation and how to use it in different scenarios. ## System requirements -To use the `devcontainer` CLI, you'll need the following on your system or CI/DevOps environment: +To use the VS Code `devcontainer` CLI, you'll need the following on your system or CI/DevOps environment: 1. [Node.js 14+](https://nodejs.org). 1. [The `docker` CLI](/docs/remote/containers#installation). @@ -70,7 +77,7 @@ Visual Studio Code has many [command line options](/docs/editor/command-line.md) ![Prompt to reopen folder within a dev container](images/devcontainer-cli/reopen-in-container.png) -With the devcontainer CLI, you can use the `devcontainer open` command to open the current folder straight into dev container mode, skipping the prompt. +With the VS Code `devcontainer` CLI, you can use the `devcontainer open` command to open the current folder straight into dev container mode, skipping the prompt. You can optionally specify the path to the folder to open, for example `devcontainer open /source/my-folder` to open the `/source/my-folder` folder within a dev container. @@ -169,7 +176,7 @@ jobs: docker push "${IMAGE_REPOSITORY}" ``` -### devcontainer CLI build options +### CLI build options The following options can be used with the `build` command: @@ -180,7 +187,7 @@ You can also type `devcontainer build --help` to see a full list of available op ### [Optional] Avoiding problems with images built using Docker -Given Dockerfiles and Docker Compose files can be used without VS Code or the `devcontainer` CLI, you may want to let users know that they should not try to build the image directly if it will not work as expected. To solve this problem, you can add a build argument that needs to be specified for things to work. +Given Dockerfiles and Docker Compose files can be used without VS Code or the VS Code `devcontainer` CLI, you may want to let users know that they should not try to build the image directly if it will not work as expected. To solve this problem, you can add a build argument that needs to be specified for things to work. For example, you could add the following to your Dockerfile: @@ -201,7 +208,7 @@ And the following in your `devcontainer.json`: } ``` -In the Docker Compose case, you can add this argument to a separate [override file to extend your configuration](/docs/remote/create-dev-container.md#extend-your-docker-compose-file-for-development) that is located in a different place in your source tree than the primary Docker Compose file +In the Docker Compose case, you can add this argument to a separate [override file to extend your configuration](/docs/remote/create-dev-container.md#extend-your-docker-compose-file-for-development) that is located in a different place in your source tree than the primary Docker Compose file. ## Next steps From 3d5359e747c81cfed3e7a0015b5c19742ca98bc1 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 4 Mar 2022 14:15:02 -0800 Subject: [PATCH 04/46] Update containers doc --- docs/remote/containers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/remote/containers.md b/docs/remote/containers.md index 3b215b4af0..f5c14b870d 100644 --- a/docs/remote/containers.md +++ b/docs/remote/containers.md @@ -288,9 +288,9 @@ The **Remote-Containers: Configure Container Features** command allows you to up We recommend pre-building images with the tools you need rather than creating and building a container image each time you open your project in a dev container. Using pre-built images will result in a faster container startup, simpler configuration, and allows you to pin to a specific version of tools to improve supply-chain security and avoid potential breaks. You can automate pre-building your image by scheduling the build using a DevOps or continuous integration (CI) service like GitHub Actions. -We recommend using the [devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly. +We recommend using the [VS Code devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly. -See the [devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#building-a-dev-container-image) for more information. +See the [VS Code devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#building-a-dev-container-image) for more information. ## Inspecting volumes From e7110fa49577e0f4149304c6977296e524104d51 Mon Sep 17 00:00:00 2001 From: luabud Date: Fri, 4 Mar 2022 14:56:18 -0800 Subject: [PATCH 05/46] Remove insiders program from docs --- docs/languages/python.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/languages/python.md b/docs/languages/python.md index 5f2db4b9d6..5362ca98d2 100644 --- a/docs/languages/python.md +++ b/docs/languages/python.md @@ -23,12 +23,6 @@ Once you have a version of Python installed, activate it using the **Python: Sel You can configure the Python extension through settings. See the [Settings reference](/docs/python/settings-reference.md). -## Insiders program - -The Insiders program allows you to try out and automatically install new versions of the Python extension prior to release, including new features and fixes. - -If you'd like to opt into the program, you can either open the Command Palette (`kb(workbench.action.showCommands)`) and select **Python: Switch to Insiders Daily/Weekly Channel** or else you can open settings (`kb(workbench.action.openSettings)`) and look for **Python: Insiders Channel** to set the channel to “daily” or “weekly”. - ## Run Python code To experience Python, create a file (using the [File Explorer](/docs/getstarted/userinterface.md#explorer)) named `hello.py` and paste in the following code (assuming Python 3): From 1be64cd7b5ed4209d4ac3fa1e3c0d54be4a73f8c Mon Sep 17 00:00:00 2001 From: luabud Date: Fri, 4 Mar 2022 14:57:28 -0800 Subject: [PATCH 06/46] Remove insiders comment --- docs/python/settings-reference.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index dfc3e99b3a..9eb5b6f49a 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -31,7 +31,6 @@ For general information about working with settings in VS Code, refer to [User a | terminal.activateEnvironment | `true` | Indicates whether to automatically activate the environment you select using the **Python: Select Interpreter** command when a new terminal is created. For example, when this setting is `true` and you select a virtual environment, the extension automatically runs the environment's *activate* command when creating a new terminal (`source env/bin/activate` on macOS/Linux; `env\scripts\activate` on Windows). | | terminal.activateEnvInCurrentTerminal | `false` | Specifies whether to activate the currently open terminal when the Python extension is activated, using the virtual environment selected. | | logging.level| `error` | Specifies the level of logging to be performed by the extension. The possible levels of logging, in increasing level of information provided, are `off`, `error`, `warn`, `info`, and `debug`. When set to `off`, which is not recommended, basic information will still be shown such as startup information and commands run by the Python extension. At the `error` level, basic information and errors will be shown. At the `warn` level, basic, error, and warning information will be shown. At the `info` level, basic, error, warning, and additional information like method execution times and return values will be shown. At this time, the `debug` level doesn't display additional information. | -| insidersChannel | `off` | Specifies whether to participate in the Insiders program and the channel to use. Set to `weekly` or `daily` to automatically download and install the latest Insiders builds of the Python extension, which include upcoming features and bug fixes. | ## Workspace symbol (tags) settings From 5367a4d370773fe2b40a714ab106bee112b264cf Mon Sep 17 00:00:00 2001 From: Prajwal Koirala <16564273+Prajwal-Koirala@users.noreply.github.com> Date: Sun, 6 Mar 2022 18:49:14 -0500 Subject: [PATCH 07/46] running into alot of system without wget or gpg --- docs/setup/linux.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/setup/linux.md b/docs/setup/linux.md index c436937ed2..14b9850618 100644 --- a/docs/setup/linux.md +++ b/docs/setup/linux.md @@ -32,6 +32,7 @@ Note that other binaries are also available on the [VS Code download page](/Down Installing the .deb package will automatically install the apt repository and signing key to enable auto-updating using the system's package manager. Alternatively, the repository and key can also be installed manually with the following script: ```bash +sudo apt-get install wget gpg wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/ sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list' From ee5a259e5747261886f4f24664e618638b9d05e0 Mon Sep 17 00:00:00 2001 From: Lessley Dennington Date: Mon, 7 Mar 2022 09:44:23 -0800 Subject: [PATCH 08/46] Update recommended Git credential helper Git Credential Manager for Mac and Linux and Git Credential Manager for Windows have been deprecated in favor of Git Credential Manager (see https://github.com/GitCredentialManager/git-credential-manager). Updating the documentation to reflect this change. --- docs/editor/versioncontrol.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/editor/versioncontrol.md b/docs/editor/versioncontrol.md index c9a7f0d858..22383d2c33 100644 --- a/docs/editor/versioncontrol.md +++ b/docs/editor/versioncontrol.md @@ -242,7 +242,12 @@ You can always set up a [credential helper](https://help.github.com/articles/cac ### How can I sign in to Git with my Azure DevOps organization that requires multi-factor authentication? -There are now [Git credential helpers](https://devblogs.microsoft.com/devops/git-credential-manager-for-mac-and-linux) that assist with multi-factor authentication. You can download these from [Git Credential Manager for Mac and Linux](https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux) and [Git Credential Manager for Windows](https://github.com/microsoft/Git-Credential-Manager-for-Windows). +[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) +(or GCM for short) is the recommended Git credential helper for Windows, +macOS, and Linux. If you're running Git for Windows, GCM has already been +installed and configured for you. If you're running on macOS or Linux, +please see the GCM [`README`](https://github.com/GitCredentialManager/git-credential-manager#download-and-install) +for setup instructions. ### I have GitHub Desktop installed on my computer but VS Code ignores it From 650cc462639de28f40a32d7767773dc1208297ca Mon Sep 17 00:00:00 2001 From: gregvanl Date: Mon, 7 Mar 2022 11:42:27 -0800 Subject: [PATCH 09/46] Update notebook guide to use 'text/x-json' --- api/extension-guides/notebook.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/extension-guides/notebook.md b/api/extension-guides/notebook.md index e09507838a..4c3f5bd1a3 100644 --- a/api/extension-guides/notebook.md +++ b/api/extension-guides/notebook.md @@ -218,10 +218,10 @@ try { Rich outputs are the most advanced form of displaying cell outputs. They allow for providing many different representations of the output data, keyed by mimetype. For example, if a cell output was to represent a GitHub Issue, the kernel might produce a rich output with several properties on its `data` field: * A `text/html` field containing a formatted view of the issue. -* An `application/json` field containing a machine readable view. +* A `text/x-json` field containing a machine readable view. * An `application/github-issue` field that a `NotebookRenderer` could use to create a fully interactive view of the issue. -In this case, the `text/html` and `application/json` views will be rendered by VS Code natively, but the `application/github-issue` view will display an error if no `NotebookRenderer` was registered to that mimetype. +In this case, the `text/html` and `text/x-json` views will be rendered by VS Code natively, but the `application/github-issue` view will display an error if no `NotebookRenderer` was registered to that mimetype. ```ts execution.replaceOutput([new vscode.NotebookCellOutput([ @@ -245,7 +245,7 @@ By default, VS Code can render the following mimetypes: VS Code will render these mimetypes as code in a built-in editor: -* application/json +* text/x-json * text/x-javascript * text/x-html * text/x-rust From 3d0dc38287ce20e7ce0aa8bdc343005477448f61 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Mon, 7 Mar 2022 12:03:13 -0800 Subject: [PATCH 10/46] Explain zsh workaround in faq Fixes #5221 --- docs/editor/integrated-terminal.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/editor/integrated-terminal.md b/docs/editor/integrated-terminal.md index 7e061209cd..7bdd4624f4 100644 --- a/docs/editor/integrated-terminal.md +++ b/docs/editor/integrated-terminal.md @@ -623,4 +623,11 @@ This normally means that the program/shell running inside the terminal requested ``` bind 'set enable-bracketed-paste off' -``` \ No newline at end of file +``` + +### Ctrl+A, Ctrl+R, etc. output ^A, ^R, etc on zsh + +This can happen if zsh is in vim mode instead of emacs mode which can happen if you set `$EDITOR` or `$VISUAL` to `vi`/`vim` in your init scripts. To workaround this you have two options: + +- Ensure that you don't set `$EDITOR` to `vi(m)`, this isn't an option if you want your git editor to work though. +- Add `bindkey -e` to your init script to set emacs explicitly. \ No newline at end of file From ad4f2223c770f33f73a5d3e3f37116ec29c135e7 Mon Sep 17 00:00:00 2001 From: Daniel Imms <2193314+Tyriar@users.noreply.github.com> Date: Mon, 7 Mar 2022 12:04:43 -0800 Subject: [PATCH 11/46] Less happens --- docs/editor/integrated-terminal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/editor/integrated-terminal.md b/docs/editor/integrated-terminal.md index 7bdd4624f4..5ddcc9cc23 100644 --- a/docs/editor/integrated-terminal.md +++ b/docs/editor/integrated-terminal.md @@ -627,7 +627,7 @@ bind 'set enable-bracketed-paste off' ### Ctrl+A, Ctrl+R, etc. output ^A, ^R, etc on zsh -This can happen if zsh is in vim mode instead of emacs mode which can happen if you set `$EDITOR` or `$VISUAL` to `vi`/`vim` in your init scripts. To workaround this you have two options: +This can happen if zsh is in vim mode instead of emacs mode due to setting `$EDITOR` or `$VISUAL` to `vi`/`vim` in your init scripts. To workaround this you have two options: - Ensure that you don't set `$EDITOR` to `vi(m)`, this isn't an option if you want your git editor to work though. - Add `bindkey -e` to your init script to set emacs explicitly. \ No newline at end of file From a1318c747696fec95fab6d9c947503425d49e732 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Mon, 7 Mar 2022 14:26:45 -0800 Subject: [PATCH 12/46] Small edits to recent update --- docs/editor/integrated-terminal.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/editor/integrated-terminal.md b/docs/editor/integrated-terminal.md index 5ddcc9cc23..a5ec4b5dc0 100644 --- a/docs/editor/integrated-terminal.md +++ b/docs/editor/integrated-terminal.md @@ -625,9 +625,11 @@ This normally means that the program/shell running inside the terminal requested bind 'set enable-bracketed-paste off' ``` -### Ctrl+A, Ctrl+R, etc. output ^A, ^R, etc on zsh +### Ctrl+A, Ctrl+R output ^A, ^R on zsh -This can happen if zsh is in vim mode instead of emacs mode due to setting `$EDITOR` or `$VISUAL` to `vi`/`vim` in your init scripts. To workaround this you have two options: +This can happen if zsh is in Vim mode instead of Emacs mode, due to setting `$EDITOR` or `$VISUAL` to `vi`/`vim` in your init scripts. -- Ensure that you don't set `$EDITOR` to `vi(m)`, this isn't an option if you want your git editor to work though. -- Add `bindkey -e` to your init script to set emacs explicitly. \ No newline at end of file +To workaround this you have two options: + +* Ensure that you don't set `$EDITOR` to `vi(m)`. However, this isn't an option if you want your Git editor to work. +* Add `bindkey -e` to your init script to set Emacs explicitly. From c1e56c2a1dce039315784069b811dbd4f03c82bb Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 08:53:51 -0800 Subject: [PATCH 13/46] Small edits to recent updates --- docs/editor/versioncontrol.md | 8 ++------ docs/languages/typescript.md | 2 +- docs/remote/devcontainer-cli.md | 8 +++++--- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/editor/versioncontrol.md b/docs/editor/versioncontrol.md index 22383d2c33..ed44fccc87 100644 --- a/docs/editor/versioncontrol.md +++ b/docs/editor/versioncontrol.md @@ -242,12 +242,8 @@ You can always set up a [credential helper](https://help.github.com/articles/cac ### How can I sign in to Git with my Azure DevOps organization that requires multi-factor authentication? -[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) -(or GCM for short) is the recommended Git credential helper for Windows, -macOS, and Linux. If you're running Git for Windows, GCM has already been -installed and configured for you. If you're running on macOS or Linux, -please see the GCM [`README`](https://github.com/GitCredentialManager/git-credential-manager#download-and-install) -for setup instructions. +[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is the recommended Git credential helper for Windows, macOS, and Linux. If you're running Git for Windows, GCM has already been installed and configured for you. If you're running on macOS or Linux, the GCM [README](https://github.com/GitCredentialManager/git-credential-manager#download-and-install) +has setup instructions. ### I have GitHub Desktop installed on my computer but VS Code ignores it diff --git a/docs/languages/typescript.md b/docs/languages/typescript.md index abb4d7e444..b15eebce40 100644 --- a/docs/languages/typescript.md +++ b/docs/languages/typescript.md @@ -369,7 +369,7 @@ Debug Node.js in VS Code using the built-in debugger. Setup is easy and there is [Linters](https://en.wikipedia.org/wiki/Lint_%28software%29) provides warnings for suspicious looking code. While VS Code does not include a built-in TypeScript linter, TypeScript linter [extensions](/docs/editor/extension-marketplace.md) available in the marketplace. -[ESLint](https://eslint.org) is a popular linter, which also supports TypeScript. The [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) integrates ESLint into VS Code so you can see linting errors right in the editor and even quickly many of fix them with [Quick Fixes](#quick-fixes). [The ESLint plugin guide](https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/README.md) details how to configure ESLint for your TypeScript projects. +[ESLint](https://eslint.org) is a popular linter, which also supports TypeScript. The [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) integrates ESLint into VS Code so you can see linting errors right in the editor and even quickly many of fix them with [Quick Fixes](#quick-fixes). [The ESLint plugin guide](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/README.md) details how to configure ESLint for your TypeScript projects. ## TypeScript extensions diff --git a/docs/remote/devcontainer-cli.md b/docs/remote/devcontainer-cli.md index f2d75bbf21..bf5efa59ca 100644 --- a/docs/remote/devcontainer-cli.md +++ b/docs/remote/devcontainer-cli.md @@ -8,13 +8,15 @@ MetaDescription: Documentation on using the VS Code devcontainer command line in DateApproved: 3/3/2022 --- # Development container command line interface + When we refer to a command line interface (CLI) for development containers, there are two varieties: -* "dev container CLI" - A reference implementation for the open dev container spec. The [current proposal](https://github.com/microsoft/dev-container-spec/issues/9) is to make a CLI available that can take a `devcontainer.json` and create and configure a dev container from it. It could be available in any IDE or editor. + +* "dev container CLI" - A reference implementation for the open dev container specification. The [current proposal](https://github.com/microsoft/dev-container-spec/issues/9) is to make a CLI available that can take a `devcontainer.json` and create and configure a development container from it. It could be available in any IDE or editor. * "Visual Studio Code `devcontainer` CLI" - A CLI that can be installed and used via the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or through an external terminal. -The former is in-progress. The latter is available today and the focus of this document. +The former is in-progress. The latter, VS Code `devcontainer` CLI, is available today and the focus of this document. -## Visual Studio Code `devcontainer` CLI +## Visual Studio Code devcontainer CLI Given the growing number of use cases for dev containers, there is a companion `devcontainer` CLI that can be used independent of the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or GitHub Codespaces. This article will walk you through its installation and how to use it in different scenarios. From d094d78b53b7b47eb6912eeab2947d06d464989f Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 09:18:01 -0800 Subject: [PATCH 14/46] Mention 1.65.1 release --- release-notes/v1_65.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/release-notes/v1_65.md b/release-notes/v1_65.md index ca1c89fed1..1120f60bae 100644 --- a/release-notes/v1_65.md +++ b/release-notes/v1_65.md @@ -5,12 +5,16 @@ PageTitle: Visual Studio Code February 2022 MetaDescription: Learn what is new in the Visual Studio Code February 2022 Release (1.65) MetaSocialImage: 1_65/release-highlights.png Date: 2022-3-3 -DownloadVersion: 1.65.0 +DownloadVersion: 1.65.1 --- # February 2022 (version 1.65) +**Update 1.65.1**: The update addresses these security [issues](https://github.com/microsoft/vscode/milestone/181?closed=1). + +--- + Welcome to the February 2022 release of Visual Studio Code. * **[New editor history navigation](#new-editor-history-navigation)** - Scope Go Back/Go Forward history to editor group or single editor. From d83ccee5d97efa59c86dcf8ecf5f15f6fa4d17b7 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 10:05:34 -0800 Subject: [PATCH 15/46] Add link to March iteration plan --- release-notes/v1_66.md | 1 + 1 file changed, 1 insertion(+) diff --git a/release-notes/v1_66.md b/release-notes/v1_66.md index 1f5dd29ac3..20924555de 100644 --- a/release-notes/v1_66.md +++ b/release-notes/v1_66.md @@ -15,6 +15,7 @@ Welcome to the Insiders build. These are the preliminary notes for the March 1.6 Until the March milestone release notes are available, you can still track our progress: +* **[March iteration plan](https://github.com/microsoft/vscode/issues/144519)** - Review what's planned for the milestone. * **[Commit log](https://github.com/Microsoft/vscode/commits/main)** - GitHub commits to the vscode open-source repository. * **[Closed issues](https://github.com/Microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22March+2022%22+is%3Aclosed)** - Resolved bugs and implemented feature requests in the milestone. From 771dc922eb9a71a23aa6aa3e3e4567aed08bed49 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 10:37:34 -0800 Subject: [PATCH 16/46] Shorten H1 to avoid line break --- docs/remote/devcontainer-cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/remote/devcontainer-cli.md b/docs/remote/devcontainer-cli.md index bf5efa59ca..d1a6a39033 100644 --- a/docs/remote/devcontainer-cli.md +++ b/docs/remote/devcontainer-cli.md @@ -4,10 +4,10 @@ Area: remote TOCTitle: devcontainer CLI PageTitle: Installing and working with the devcontainer CLI ContentId: 8946213d-716e-41ca-955f-944a41c70353 -MetaDescription: Documentation on using the VS Code devcontainer command line interface with the Visual Studio Code Remote - Containers extension +MetaDescription: Documentation on using the VS Code development container (devcontainer) command line interface with the Visual Studio Code Remote - Containers extension DateApproved: 3/3/2022 --- -# Development container command line interface +# Development container CLI When we refer to a command line interface (CLI) for development containers, there are two varieties: From aa0daa56bcaef803b85e67c48dc621bb46abbb76 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 10:56:39 -0800 Subject: [PATCH 17/46] Update 1.65.1 link to issue query --- release-notes/v1_65.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release-notes/v1_65.md b/release-notes/v1_65.md index 1120f60bae..98dd558d04 100644 --- a/release-notes/v1_65.md +++ b/release-notes/v1_65.md @@ -9,7 +9,7 @@ DownloadVersion: 1.65.1 --- # February 2022 (version 1.65) -**Update 1.65.1**: The update addresses these security [issues](https://github.com/microsoft/vscode/milestone/181?closed=1). +**Update 1.65.1**: The update addresses these security [issues](https://github.com/microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22February+2022+Recovery+1%22+is%3Aclosed). From 7358ca6a4005e393d742627c4a9d7b34f7c4cec5 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 12:09:03 -0800 Subject: [PATCH 18/46] Tutorial problem blog post --- blogs/2022/03/08/add-dev-container.gif | 3 + blogs/2022/03/08/container-file-structure.png | 3 + blogs/2022/03/08/container-logs.png | 3 + blogs/2022/03/08/docker-extension.png | 3 + blogs/2022/03/08/laravel-app.png | 3 + blogs/2022/03/08/port-forwarding.png | 3 + blogs/2022/03/08/remote-indicator.png | 3 + .../2022/03/08/reopen-in-container-prompt.png | 3 + blogs/2022/03/08/terminal.png | 3 + blogs/2022/03/08/the-tutorial-problem.md | 139 ++++++++++++++++++ 10 files changed, 166 insertions(+) create mode 100644 blogs/2022/03/08/add-dev-container.gif create mode 100644 blogs/2022/03/08/container-file-structure.png create mode 100644 blogs/2022/03/08/container-logs.png create mode 100644 blogs/2022/03/08/docker-extension.png create mode 100644 blogs/2022/03/08/laravel-app.png create mode 100644 blogs/2022/03/08/port-forwarding.png create mode 100644 blogs/2022/03/08/remote-indicator.png create mode 100644 blogs/2022/03/08/reopen-in-container-prompt.png create mode 100644 blogs/2022/03/08/terminal.png create mode 100644 blogs/2022/03/08/the-tutorial-problem.md diff --git a/blogs/2022/03/08/add-dev-container.gif b/blogs/2022/03/08/add-dev-container.gif new file mode 100644 index 0000000000..3a9f43a88a --- /dev/null +++ b/blogs/2022/03/08/add-dev-container.gif @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:40e6549a7d76a4fb3bb3e8bdbeba0113536bc49bd6a8a9df40590fa5a5596289 +size 15925134 diff --git a/blogs/2022/03/08/container-file-structure.png b/blogs/2022/03/08/container-file-structure.png new file mode 100644 index 0000000000..457fa522bb --- /dev/null +++ b/blogs/2022/03/08/container-file-structure.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c36741cb1f49a446b3031f3e0c6fc780ddc572d18caebbcb29b8d4566c7503a +size 59327 diff --git a/blogs/2022/03/08/container-logs.png b/blogs/2022/03/08/container-logs.png new file mode 100644 index 0000000000..d65fa9d350 --- /dev/null +++ b/blogs/2022/03/08/container-logs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7b96743d51813b2d0decad7a5d671cff738ce44398b51c7b7372b5531d4d3fb1 +size 276068 diff --git a/blogs/2022/03/08/docker-extension.png b/blogs/2022/03/08/docker-extension.png new file mode 100644 index 0000000000..19925e8b61 --- /dev/null +++ b/blogs/2022/03/08/docker-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4c10448aece3502b13325d0d79b236af4e5ca2089bddaed3b42e433e07359c08 +size 51825 diff --git a/blogs/2022/03/08/laravel-app.png b/blogs/2022/03/08/laravel-app.png new file mode 100644 index 0000000000..40bd3429c7 --- /dev/null +++ b/blogs/2022/03/08/laravel-app.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:648b0a8d9d789b735b8914e16b49fc1066655bd3784c1d2aead5e75ec573719a +size 91848 diff --git a/blogs/2022/03/08/port-forwarding.png b/blogs/2022/03/08/port-forwarding.png new file mode 100644 index 0000000000..dd0966164b --- /dev/null +++ b/blogs/2022/03/08/port-forwarding.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:38d6fb78de3dbc6ddec892a75ff8ca31d578917758fe43f8848d519e33fbff65 +size 13144 diff --git a/blogs/2022/03/08/remote-indicator.png b/blogs/2022/03/08/remote-indicator.png new file mode 100644 index 0000000000..796929419d --- /dev/null +++ b/blogs/2022/03/08/remote-indicator.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:553ef71316f1c7e477d5fbdd17151e33613a1b2b9efed2d64de2e5aba308603a +size 55563 diff --git a/blogs/2022/03/08/reopen-in-container-prompt.png b/blogs/2022/03/08/reopen-in-container-prompt.png new file mode 100644 index 0000000000..4a4430b3df --- /dev/null +++ b/blogs/2022/03/08/reopen-in-container-prompt.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1d41373104ccc3f491fcfae0398dcd09c7885dc8823a3afaad5c77706cbb1eee +size 37873 diff --git a/blogs/2022/03/08/terminal.png b/blogs/2022/03/08/terminal.png new file mode 100644 index 0000000000..572e002603 --- /dev/null +++ b/blogs/2022/03/08/terminal.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:628c2ab497aa960c243eee081dfca8d00fb0fc5d34bf79afd756d64f1d38bfd0 +size 13323 diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md new file mode 100644 index 0000000000..6778b7ec74 --- /dev/null +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -0,0 +1,139 @@ +--- +Order: 71 +TOCTitle: Solving the "Tutorial Problem" +PageTitle: Solving the "Tutorial Problem" +MetaDescription: How Laravel uses containerized dev environments to make a better tutorial +Date: 2022-03-01 +Author: Burke Holland +--- + +# Solving the "Tutorial" problem + +March 8, 2022 by Burke Holland, [@burkeholland](https://twitter.com/burkeholland) + +Writing a great tutorial ain't easy. I should know - I've written a lot of them, and not every one was a smashing success. + +As a case in point, our very own tutorial on [how to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - somewhere in the neighborhood of 4 - 6%. To figure out where people were giving up, we conducted user studies - which is where someone goes through the tutorial while we observe their progress. + +During these user studies it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was** **reading it**. + +## Nobody reads + +When I was in school, they gave us a test called, "[Following Directions](https://www.uen.org/lessonplan/download/44825?lessonId=27659&segmentTypeId=2)". It's a timed test with about 15 or so questions with various problems or puzzles. They gave us 5 minutes to complete the test. The questions were not easy, so you had to get right to it in order to finish in the allotted time. The instructions at the very top of the test said to "read the entire test before starting it". You only have 5 minutes so it's a pure waste of time to *read* the entire test first. Except, burried somewhere down towards the end of the test, one of the questions says, "Skip all questions and only complete number 3". In my recollection, only 2 students out of the entire class got this assignment correct; which was precisely the point of the exercise. + +It is natural human behavior to skip over explanatory text and begin with solutions straight away. I can relate to this. When I'm doing tutorials, my eyes are scanning for blocks of code because I'm pretty sure if you just tell me what to do next, I can figure out the *why* myself. And yet, when I'm writing tutorials, I somehow forget that and go full Tolstoy. + +Back to our own tutorial - we watched as people would get stuck on some detail that was clearly explained right above the step they were trying to complete. What's worse is that the more text that a page had on it, the more likely people were to ignore it. + +What we learned is that **if you want people to be successful with your tutorial, you need to remove as much of that tutorial as possible**. Tell people only what they need to know to be successful and either delete or abstract away as many things as you possibly can. + +One of ways you can pair down your own tutorials is to completely remove any environment setup steps using preconfigured container dev environments. + +## Containerized development environments + +A significant chunk of any tutorial is usually dedicated to a laundry list of pre-requisites and environment setup. I distinctly recall trying to learn Ruby on Rails and spending most of the time trying to get Ruby installed correctly on Windows - wondering what in the world a "gem" was and why they were all somehow missing. + +The idea behind containerized dev environments is that you develop inside of a Docker container. This makes it possible to have a completely portable, fully configured development environment that you can stand up or knock down at will. You could then give that entire environment to someone as nothing more than a set of configuration files. + +But how do you develop INSIDE of a container? It's not like containers have a UI where you can just launch VS Code. + +The [Remote-Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) [extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) does exactly this. It contains both the mechanism for configuring a Docker container as a dev environment, as well as allowing you to connect to that environment from VS Code. It does this by installing a small server component within the container that your local VS Code talks to. You then develop just like you would if you were local, but VS Code is attached to the container environment instead of your local environment. + +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people *don't* (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. For instance, here I set up a new Python container and then add the Azure CLI, the Dotnet CLI and Powershell... + +![Adding a dev container configuration to a Python project](add-dev-container.gif) + +This process adds a ".devcontainer" folder to this project with the necessary "Dockerfile" included. It also adds a "devcontainer.json" file, which is a standard for defining aspects of a dev container, like which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. + +In this way, it's possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. + +Some folks are already using a dev container based approach to get their users up and running quickly with what are otherwise very complex environments. A great example of this is the [Laravel framework for PHP](https://laravel.com/docs/9.x). + +## The Laravel solution + +Laravel is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. + +Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). In order to get started from scratch with Laravel, a MySQL Server and a Redis Cache, you only have to run a single command... + +```bash + curl -s "https://laravel.build/example-app?with=mysql,redis" | bash +``` + +This creates a new project with a "docker-compose" file. This file sets up 3 containers - an application container, a MySQL container and a Redis container. You don't have to know anything about containers or any of those 3 services. Sail abstracts all of this away for you. You then execute the Sail command to spin up the environment... + +```bash + ./vendor/bin/sail up +``` + +The sample application just runs. No installing PHP. No Laravel. No dependency resolutions steps. Just immediate success. + +![An example Laravel application running in the browser on localhost](laravel-app.png) + +I specified that our project has a MySQL Server and a Redis Cache, so we actually get 3 containers when the project spins up. We can see that using the [Docker extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker&WT.mc_id=devcloud-0000-cxa). + +![The Docker extension in VS Code](docker-extension.png) + +These containers are networked together so that we can call the MySQL or Redis cache containers from the app container. + +If you inspect the app container, you'll see your project in the /var/www/html folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. + +![The file structure of the Laravel project in a container](container-file-structure.png) + +## Adding Remote Containers + +Support has also been added for the [Remote-Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). To add the proper dev container configuration to this project, you can scaffold the same project and add the `&devcontainer` flag. + +```bash + curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash +``` + +> Note that if you want to add a devcontainer to an existing Sail/Laravel project, you can do that by running `php artisan sail:install --devcontainer` + +This creates the same project configuration, but will include a `.devcontainer` folder. VS Code will automatically detect that folder and prompt you to reopen the project in a container thereby skipping the required `sail up` step. + +![A notification in VS Code saying "Reopen in container"](reopen-in-container-prompt.png) + +In this case, VS Code attaches to the container so you are developing *within* the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... + +![The remote indicator in VS Code showing connection to a container](remote-indicator.png) + +Developing in the container as opposed to outside of it has some distinct benefits. + +### Development context mirrors app context + +When connected to the container, the context you are developing in is the same as the one where the application is running. So your terminal becomes the terminal of the container... + +![The VS Code terminal connected to the running container instance](terminal.png) + +Remote-Containers also gives you a more complete view of what's going on, like which ports are forwarded - just in case you forget where your application is running. + +![The port forwarding view in VS Code showing port 80 forwarded](port-forwarding.png) + +The Laravel application starts automatically and the application logs are piped to the container logs. Since you probably want to see what's going on in the application, The Remote-Containers extension provides a new view in VS Code where you can see all running containers, as well as connect to a stream container logs. + +![The Laravel application container logs in VS Code](container-logs.png) + +### Automate the dev environment setup + +The best possible developer experience is going to include customizations for the editor. This includes settings for the editor itself, and any extensions or other support that needs to be added to the out-of-the-box experience. + +For VS Code and Laravel, extensions are suggested in the "devcontainer.json", but commented out so that they are not installed automatically. This allows the user to pick from a set of already identified extensions instead of having to go hunt for the right way to configure their editor. + +```json + ... + "extensions": [ + // "mikestead.dotenv", + // "amiralizadeh9480.laravel-extra-intellisense", + // "ryannaddy.laravel-artisan", + // "onecentlin.laravel5-snippets", + // "onecentlin.laravel-blade" + ], +``` + +## Read less, do more + +People don't read. And that should be OK. Laravel's tutorials aren't necessarily shorter than any others, but the important thing is that if you read none of it and just run the commands, it works. Dev containers make this possible. Now if only we could figure out how to make a dev container for our dev container tutorial... + +Happy Coding! + +Burke Holland ([@burkeholland](https://twitter.com/burkeholland)) From aca1c559b8ef7f4494f2e55e1c9486d313bc966a Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 12:38:46 -0800 Subject: [PATCH 19/46] Edit and formatting pass --- blogs/2022/03/08/the-tutorial-problem.md | 38 ++++++++++++------------ 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 6778b7ec74..53e3cf8101 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -3,7 +3,7 @@ Order: 71 TOCTitle: Solving the "Tutorial Problem" PageTitle: Solving the "Tutorial Problem" MetaDescription: How Laravel uses containerized dev environments to make a better tutorial -Date: 2022-03-01 +Date: 2022-03-08 Author: Burke Holland --- @@ -15,35 +15,35 @@ Writing a great tutorial ain't easy. I should know - I've written a lot of them, As a case in point, our very own tutorial on [how to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - somewhere in the neighborhood of 4 - 6%. To figure out where people were giving up, we conducted user studies - which is where someone goes through the tutorial while we observe their progress. -During these user studies it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was** **reading it**. +During these user studies, it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was** **reading it**. ## Nobody reads -When I was in school, they gave us a test called, "[Following Directions](https://www.uen.org/lessonplan/download/44825?lessonId=27659&segmentTypeId=2)". It's a timed test with about 15 or so questions with various problems or puzzles. They gave us 5 minutes to complete the test. The questions were not easy, so you had to get right to it in order to finish in the allotted time. The instructions at the very top of the test said to "read the entire test before starting it". You only have 5 minutes so it's a pure waste of time to *read* the entire test first. Except, burried somewhere down towards the end of the test, one of the questions says, "Skip all questions and only complete number 3". In my recollection, only 2 students out of the entire class got this assignment correct; which was precisely the point of the exercise. +When I was in school, they gave us a test called, "[Following Directions](https://www.uen.org/lessonplan/download/44825?lessonId=27659&segmentTypeId=2)". It's a timed test with about 15 or so questions with various problems or puzzles. They gave us 5 minutes to complete the test. The questions were not easy, so you had to get right to it in order to finish in the allotted time. The instructions at the very top of the test said to "read the entire test before starting it". You only have 5 minutes so it's a pure waste of time to **read** the entire test first. Except, buried somewhere down towards the end of the test, one of the questions says, "Skip all questions and only complete number 3". In my recollection, only two students out of the entire class got this assignment correct, which was precisely the point of the exercise. -It is natural human behavior to skip over explanatory text and begin with solutions straight away. I can relate to this. When I'm doing tutorials, my eyes are scanning for blocks of code because I'm pretty sure if you just tell me what to do next, I can figure out the *why* myself. And yet, when I'm writing tutorials, I somehow forget that and go full Tolstoy. +It is natural human behavior to skip over explanatory text and begin with solutions straight away. I can relate to this. When I'm doing tutorials, my eyes are scanning for blocks of code because I'm pretty sure if you just tell me what to do next, I can figure out the **why** myself. And yet, when I'm writing tutorials, I somehow forget that and go full Tolstoy. Back to our own tutorial - we watched as people would get stuck on some detail that was clearly explained right above the step they were trying to complete. What's worse is that the more text that a page had on it, the more likely people were to ignore it. What we learned is that **if you want people to be successful with your tutorial, you need to remove as much of that tutorial as possible**. Tell people only what they need to know to be successful and either delete or abstract away as many things as you possibly can. -One of ways you can pair down your own tutorials is to completely remove any environment setup steps using preconfigured container dev environments. +One of ways you can pair down your own tutorials is to completely remove any environment setup steps using preconfigured container development environments. ## Containerized development environments A significant chunk of any tutorial is usually dedicated to a laundry list of pre-requisites and environment setup. I distinctly recall trying to learn Ruby on Rails and spending most of the time trying to get Ruby installed correctly on Windows - wondering what in the world a "gem" was and why they were all somehow missing. -The idea behind containerized dev environments is that you develop inside of a Docker container. This makes it possible to have a completely portable, fully configured development environment that you can stand up or knock down at will. You could then give that entire environment to someone as nothing more than a set of configuration files. +The idea behind containerized dev environments is that you develop inside of a [Docker](https://www.docker.com) container. This makes it possible to have a completely portable, fully configured development environment that you can stand up or knock down at will. You could then give that entire environment to someone as nothing more than a set of configuration files. -But how do you develop INSIDE of a container? It's not like containers have a UI where you can just launch VS Code. +But how do you develop **inside** of a container? It's not like containers have a UI where you can just launch VS Code. -The [Remote-Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) [extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) does exactly this. It contains both the mechanism for configuring a Docker container as a dev environment, as well as allowing you to connect to that environment from VS Code. It does this by installing a small server component within the container that your local VS Code talks to. You then develop just like you would if you were local, but VS Code is attached to the container environment instead of your local environment. +The [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code does exactly this. It contains both the mechanism for configuring a Docker container as a dev environment, as well as allowing you to connect to that environment from VS Code. It does this by installing a small server component within the container that your local VS Code talks to. You then develop just like you would if you were local, but VS Code is attached to the container environment instead of your local environment. -In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people *don't* (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. For instance, here I set up a new Python container and then add the Azure CLI, the Dotnet CLI and Powershell... +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. For instance, here I set up a new Python container and then add the Azure CLI, the Dotnet CLI and PowerShell... ![Adding a dev container configuration to a Python project](add-dev-container.gif) -This process adds a ".devcontainer" folder to this project with the necessary "Dockerfile" included. It also adds a "devcontainer.json" file, which is a standard for defining aspects of a dev container, like which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. +This process adds a `.devcontainer` folder to this project with the necessary `Dockerfile` included. It also adds a `devcontainer.json` file, which is a standard for defining aspects of a dev container, such as which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. In this way, it's possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. @@ -53,13 +53,13 @@ Some folks are already using a dev container based approach to get their users u Laravel is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. -Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). In order to get started from scratch with Laravel, a MySQL Server and a Redis Cache, you only have to run a single command... +Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). In order to get started from scratch with Laravel, a MySQL Server, and a Redis Cache, you only have to run a single command... ```bash curl -s "https://laravel.build/example-app?with=mysql,redis" | bash ``` -This creates a new project with a "docker-compose" file. This file sets up 3 containers - an application container, a MySQL container and a Redis container. You don't have to know anything about containers or any of those 3 services. Sail abstracts all of this away for you. You then execute the Sail command to spin up the environment... +This creates a new project with a `docker-compose` file. This file sets up three containers - an application container, a MySQL container, and a Redis container. You don't have to know anything about containers or any of those three services. Sail abstracts all of this away for you. You then execute the Sail command to spin up the environment... ```bash ./vendor/bin/sail up @@ -69,19 +69,19 @@ The sample application just runs. No installing PHP. No Laravel. No dependency r ![An example Laravel application running in the browser on localhost](laravel-app.png) -I specified that our project has a MySQL Server and a Redis Cache, so we actually get 3 containers when the project spins up. We can see that using the [Docker extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker&WT.mc_id=devcloud-0000-cxa). +I specified that our project has a MySQL Server and a Redis Cache, so we actually get three containers when the project spins up. We can see that using the [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) extension for VS Code. ![The Docker extension in VS Code](docker-extension.png) These containers are networked together so that we can call the MySQL or Redis cache containers from the app container. -If you inspect the app container, you'll see your project in the /var/www/html folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. +If you inspect the app container, you'll see your project in the `/var/www/html` folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. ![The file structure of the Laravel project in a container](container-file-structure.png) ## Adding Remote Containers -Support has also been added for the [Remote-Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). To add the proper dev container configuration to this project, you can scaffold the same project and add the `&devcontainer` flag. +Support has also been added for the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. To add the proper dev container configuration to this project, you can scaffold the same project and add the `&devcontainer` flag. ```bash curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash @@ -93,7 +93,7 @@ This creates the same project configuration, but will include a `.devcontainer` ![A notification in VS Code saying "Reopen in container"](reopen-in-container-prompt.png) -In this case, VS Code attaches to the container so you are developing *within* the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... +In this case, VS Code attaches to the container so you are developing **within** the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... ![The remote indicator in VS Code showing connection to a container](remote-indicator.png) @@ -105,11 +105,11 @@ When connected to the container, the context you are developing in is the same a ![The VS Code terminal connected to the running container instance](terminal.png) -Remote-Containers also gives you a more complete view of what's going on, like which ports are forwarded - just in case you forget where your application is running. +Remote - Containers also gives you a more complete view of what's going on, such as which ports are forwarded - just in case you forget where your application is running. ![The port forwarding view in VS Code showing port 80 forwarded](port-forwarding.png) -The Laravel application starts automatically and the application logs are piped to the container logs. Since you probably want to see what's going on in the application, The Remote-Containers extension provides a new view in VS Code where you can see all running containers, as well as connect to a stream container logs. +The Laravel application starts automatically and the application logs are piped to the container logs. Since you probably want to see what's going on in the application, the Remote - Containers extension provides a new view in VS Code, where you can see all running containers, as well as connect to stream container logs. ![The Laravel application container logs in VS Code](container-logs.png) @@ -117,7 +117,7 @@ The Laravel application starts automatically and the application logs are piped The best possible developer experience is going to include customizations for the editor. This includes settings for the editor itself, and any extensions or other support that needs to be added to the out-of-the-box experience. -For VS Code and Laravel, extensions are suggested in the "devcontainer.json", but commented out so that they are not installed automatically. This allows the user to pick from a set of already identified extensions instead of having to go hunt for the right way to configure their editor. +For VS Code and Laravel, extensions are suggested in the `devcontainer.json`, but commented out so that they are not installed automatically. This allows the user to pick from a set of already identified extensions instead of having to go hunt for the right way to configure their editor. ```json ... From 069297e15bf85287d41a27657109b4d992fac8aa Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 13:31:49 -0800 Subject: [PATCH 20/46] Remove double quotes in metadata --- blogs/2022/03/08/the-tutorial-problem.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 53e3cf8101..4778b1c2ff 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -1,7 +1,7 @@ --- Order: 71 -TOCTitle: Solving the "Tutorial Problem" -PageTitle: Solving the "Tutorial Problem" +TOCTitle: Solving the Tutorial Problem +PageTitle: Solving the Tutorial Problem MetaDescription: How Laravel uses containerized dev environments to make a better tutorial Date: 2022-03-08 Author: Burke Holland @@ -15,7 +15,7 @@ Writing a great tutorial ain't easy. I should know - I've written a lot of them, As a case in point, our very own tutorial on [how to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - somewhere in the neighborhood of 4 - 6%. To figure out where people were giving up, we conducted user studies - which is where someone goes through the tutorial while we observe their progress. -During these user studies, it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was** **reading it**. +During these user studies, it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was reading it**. ## Nobody reads From a4282167dec719dae8378073a746d8495d40c7e5 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 8 Mar 2022 14:35:40 -0800 Subject: [PATCH 21/46] Remove blog post from TOC --- blogs/2022/03/08/the-tutorial-problem.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 4778b1c2ff..03a0f568e5 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -1,5 +1,5 @@ --- -Order: 71 +Order: TOCTitle: Solving the Tutorial Problem PageTitle: Solving the Tutorial Problem MetaDescription: How Laravel uses containerized dev environments to make a better tutorial From 7cf491bb3b0835392741e757d2d25f55f94d51a8 Mon Sep 17 00:00:00 2001 From: Burke Holland Date: Wed, 9 Mar 2022 09:51:13 -0600 Subject: [PATCH 22/46] add edits from Erich --- .../08/dev-containers-tutorial-screenshot.png | 3 ++ .../03/08/remote-containers-extension.png | 3 ++ blogs/2022/03/08/the-tutorial-problem.md | 46 ++++++++++--------- 3 files changed, 31 insertions(+), 21 deletions(-) create mode 100644 blogs/2022/03/08/dev-containers-tutorial-screenshot.png create mode 100644 blogs/2022/03/08/remote-containers-extension.png diff --git a/blogs/2022/03/08/dev-containers-tutorial-screenshot.png b/blogs/2022/03/08/dev-containers-tutorial-screenshot.png new file mode 100644 index 0000000000..a235064b39 --- /dev/null +++ b/blogs/2022/03/08/dev-containers-tutorial-screenshot.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a0a5301f54b8f27b9bead8f01461361cb791058333d55052e8a477ed69362cee +size 39567 diff --git a/blogs/2022/03/08/remote-containers-extension.png b/blogs/2022/03/08/remote-containers-extension.png new file mode 100644 index 0000000000..88d1113604 --- /dev/null +++ b/blogs/2022/03/08/remote-containers-extension.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8ce199ceb26320d0807f4aa22ae060609423089dd1a900b546b7daa836f285e9 +size 36128 diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 03a0f568e5..5ceb8673c2 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -11,49 +11,53 @@ Author: Burke Holland March 8, 2022 by Burke Holland, [@burkeholland](https://twitter.com/burkeholland) -Writing a great tutorial ain't easy. I should know - I've written a lot of them, and not every one was a smashing success. +Writing a great tutorial isn't easy. I should know - I've written a lot of them, and not every one was a smashing success. -As a case in point, our very own tutorial on [how to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - somewhere in the neighborhood of 4 - 6%. To figure out where people were giving up, we conducted user studies - which is where someone goes through the tutorial while we observe their progress. - -During these user studies, it became immediately clear to us why people weren't able to complete the tutorial: **Nobody was reading it**. +As it turns out making a great tutorial isn't about _what_ you write, it's about how whether developers can be successful without having to read every word. In this article we'll look how dev containers can reduce the errors a user might encounter, and how the [Laravel PHP project](https://laravel.com/) elegantly implements this in their own tutorials to great effect. ## Nobody reads -When I was in school, they gave us a test called, "[Following Directions](https://www.uen.org/lessonplan/download/44825?lessonId=27659&segmentTypeId=2)". It's a timed test with about 15 or so questions with various problems or puzzles. They gave us 5 minutes to complete the test. The questions were not easy, so you had to get right to it in order to finish in the allotted time. The instructions at the very top of the test said to "read the entire test before starting it". You only have 5 minutes so it's a pure waste of time to **read** the entire test first. Except, buried somewhere down towards the end of the test, one of the questions says, "Skip all questions and only complete number 3". In my recollection, only two students out of the entire class got this assignment correct, which was precisely the point of the exercise. +Our very own tutorial on [How to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - about 4 - 6%. + +![dev containers learn module screenshot](dev-containers-tutorial-screenshot.png) -It is natural human behavior to skip over explanatory text and begin with solutions straight away. I can relate to this. When I'm doing tutorials, my eyes are scanning for blocks of code because I'm pretty sure if you just tell me what to do next, I can figure out the **why** myself. And yet, when I'm writing tutorials, I somehow forget that and go full Tolstoy. +To figure out where people were giving up, we conducted user studies and watched as people tried to complete our tutorial. It was...painful. -Back to our own tutorial - we watched as people would get stuck on some detail that was clearly explained right above the step they were trying to complete. What's worse is that the more text that a page had on it, the more likely people were to ignore it. +It was immediately clear why people couldn't complete the tutorial: **Nobody was reading it**. People skipped right over the instructions and went directly to the action steps. Inevitably, they would get stuck because they made an error they wouldn't have made if they had read the instructions. -What we learned is that **if you want people to be successful with your tutorial, you need to remove as much of that tutorial as possible**. Tell people only what they need to know to be successful and either delete or abstract away as many things as you possibly can. +Penn State Professor [John M. Carroll](https://jcarroll.ist.psu.edu/) talks about this in his seminal book, [The Nurnberg Funnel - Designing Minimalist Instruction for Practical Computer Skill](https://mitpress.mit.edu/books/nurnberg-funnel). He writes, "[learners] are too busy learning to make much use of the instruction. This is the paradox of sense making." -One of ways you can pair down your own tutorials is to completely remove any environment setup steps using preconfigured container development environments. +I can relate to this, and you probably can too. When I'm going through a tutorial, my eyes are scanning for blocks of code because I'm trying to learn by doing. I'm literally too busy learning to read the instructions. + +**People aren't going to read your tutorial.** Or at least not as much as you wish they would. The best that you can do is remove as many places as possible where the reader might make an error in the learning process. One way to do that is to completely remove any environment setup steps using preconfigured container environments. ## Containerized development environments A significant chunk of any tutorial is usually dedicated to a laundry list of pre-requisites and environment setup. I distinctly recall trying to learn Ruby on Rails and spending most of the time trying to get Ruby installed correctly on Windows - wondering what in the world a "gem" was and why they were all somehow missing. -The idea behind containerized dev environments is that you develop inside of a [Docker](https://www.docker.com) container. This makes it possible to have a completely portable, fully configured development environment that you can stand up or knock down at will. You could then give that entire environment to someone as nothing more than a set of configuration files. +The idea behind containerized dev environments is that you develop inside of a [Docker](https://www.docker.com) container. This makes it possible to have a completely portable, fully configured development environment that you can stand up or knock down at will. You could then give that environment to someone as nothing more than a set of configuration files. But how do you develop **inside** of a container? It's not like containers have a UI where you can just launch VS Code. The [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code does exactly this. It contains both the mechanism for configuring a Docker container as a dev environment, as well as allowing you to connect to that environment from VS Code. It does this by installing a small server component within the container that your local VS Code talks to. You then develop just like you would if you were local, but VS Code is attached to the container environment instead of your local environment. -In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. For instance, here I set up a new Python container and then add the Azure CLI, the Dotnet CLI and PowerShell... +![The remote containers extension screenshot from extension gallery](remote-containers-extension.png) + +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you though selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case I add the Azure CLI, Dotnet CLI and Powershell… ![Adding a dev container configuration to a Python project](add-dev-container.gif) -This process adds a `.devcontainer` folder to this project with the necessary `Dockerfile` included. It also adds a `devcontainer.json` file, which is a standard for defining aspects of a dev container, such as which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. +This process adds a “.devcontainer” folder to this project with the necessary “Dockerfile” included. It also adds a “devcontainer.json” file, which is a standard for defining aspects of a dev container, like which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. -In this way, it's possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. +In this way, it’s possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. -Some folks are already using a dev container based approach to get their users up and running quickly with what are otherwise very complex environments. A great example of this is the [Laravel framework for PHP](https://laravel.com/docs/9.x). +Some folks are already using a dev container-based approach to get their users up and running quickly with what are otherwise very complex environments. A great example of this is the Laravel framework for PHP. ## The Laravel solution -Laravel is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. +[Laravel](https://laravel.com/) is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. -Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). In order to get started from scratch with Laravel, a MySQL Server, and a Redis Cache, you only have to run a single command... +Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). To get started from scratch with Laravel, a MySQL Server, and a Redis Cache, you only have to run a single command... ```bash curl -s "https://laravel.build/example-app?with=mysql,redis" | bash @@ -75,7 +79,7 @@ I specified that our project has a MySQL Server and a Redis Cache, so we actuall These containers are networked together so that we can call the MySQL or Redis cache containers from the app container. -If you inspect the app container, you'll see your project in the `/var/www/html` folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. +If you connect an interactive terminal to the “sail-8.1/app container”, you’ll see your project in the /var/www/html folder. Because Docker “mounts” the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. ![The file structure of the Laravel project in a container](container-file-structure.png) @@ -93,7 +97,7 @@ This creates the same project configuration, but will include a `.devcontainer` ![A notification in VS Code saying "Reopen in container"](reopen-in-container-prompt.png) -In this case, VS Code attaches to the container so you are developing **within** the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... +VS Code attaches to the container, so you are developing **within** the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... ![The remote indicator in VS Code showing connection to a container](remote-indicator.png) @@ -105,11 +109,11 @@ When connected to the container, the context you are developing in is the same a ![The VS Code terminal connected to the running container instance](terminal.png) -Remote - Containers also gives you a more complete view of what's going on, such as which ports are forwarded - just in case you forget where your application is running. +The Remote - Containers extension also gives you a more complete view of what's going on, such as which ports are forwarded - just in case you forget where your application is running. ![The port forwarding view in VS Code showing port 80 forwarded](port-forwarding.png) -The Laravel application starts automatically and the application logs are piped to the container logs. Since you probably want to see what's going on in the application, the Remote - Containers extension provides a new view in VS Code, where you can see all running containers, as well as connect to stream container logs. +The Laravel application starts automatically, and the application logs are piped to the container logs. Since you probably want to see what's going on in the application, the Remote - Containers extension provides a new view in VS Code, where you can see all running containers, as well as connect to stream container logs. ![The Laravel application container logs in VS Code](container-logs.png) @@ -132,7 +136,7 @@ For VS Code and Laravel, extensions are suggested in the `devcontainer.json`, bu ## Read less, do more -People don't read. And that should be OK. Laravel's tutorials aren't necessarily shorter than any others, but the important thing is that if you read none of it and just run the commands, it works. Dev containers make this possible. Now if only we could figure out how to make a dev container for our dev container tutorial... +People don't read. And that should be OK. Laravel's tutorials aren't necessarily shorter than any others, but the important thing is that if you skip to the code and just run the commands, it works. Dev containers make that possible. Now if only we could figure out how to make a dev container for our own [How to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) tutorial... Happy Coding! From b30a0eda4df74b6df18d6072177eedce40885a97 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Wed, 9 Mar 2022 13:18:22 -0800 Subject: [PATCH 23/46] Small edits and formatting, add gray border to light image --- .../08/dev-containers-tutorial-screenshot.png | 4 ++-- blogs/2022/03/08/the-tutorial-problem.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/blogs/2022/03/08/dev-containers-tutorial-screenshot.png b/blogs/2022/03/08/dev-containers-tutorial-screenshot.png index a235064b39..8c74c73cc3 100644 --- a/blogs/2022/03/08/dev-containers-tutorial-screenshot.png +++ b/blogs/2022/03/08/dev-containers-tutorial-screenshot.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:a0a5301f54b8f27b9bead8f01461361cb791058333d55052e8a477ed69362cee -size 39567 +oid sha256:161708429472850e09f50c75800b5b506b3306a8c6c59d8854e12fdbc7748f4a +size 34608 diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 5ceb8673c2..3776bf26ca 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -13,19 +13,19 @@ March 8, 2022 by Burke Holland, [@burkeholland](https://twitter.com/burkeholland Writing a great tutorial isn't easy. I should know - I've written a lot of them, and not every one was a smashing success. -As it turns out making a great tutorial isn't about _what_ you write, it's about how whether developers can be successful without having to read every word. In this article we'll look how dev containers can reduce the errors a user might encounter, and how the [Laravel PHP project](https://laravel.com/) elegantly implements this in their own tutorials to great effect. +As it turns out making a great tutorial isn't about **what** you write, it's about whether developers can be successful without having to read every word. In this article, we'll look how development containers can reduce the errors a user might encounter, and how the [Laravel PHP project](https://laravel.com/) elegantly implements this in their own tutorials to great effect. ## Nobody reads -Our very own tutorial on [How to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - about 4 - 6%. +Our very own tutorial on [how to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) has long had low completion rates - about 4 - 6%. ![dev containers learn module screenshot](dev-containers-tutorial-screenshot.png) To figure out where people were giving up, we conducted user studies and watched as people tried to complete our tutorial. It was...painful. -It was immediately clear why people couldn't complete the tutorial: **Nobody was reading it**. People skipped right over the instructions and went directly to the action steps. Inevitably, they would get stuck because they made an error they wouldn't have made if they had read the instructions. +It was immediately clear why people couldn't complete the tutorial: **Nobody was reading it**. People skipped right over the instructions and went directly to the action steps. Inevitably, they would get stuck because they made an error that they wouldn't have made if they had read the instructions. -Penn State Professor [John M. Carroll](https://jcarroll.ist.psu.edu/) talks about this in his seminal book, [The Nurnberg Funnel - Designing Minimalist Instruction for Practical Computer Skill](https://mitpress.mit.edu/books/nurnberg-funnel). He writes, "[learners] are too busy learning to make much use of the instruction. This is the paradox of sense making." +Penn State Professor [John M. Carroll](https://jcarroll.ist.psu.edu/) talks about this in his seminal book, [The Nurnberg Funnel - Designing Minimalist Instruction for Practical Computer Skill](https://mitpress.mit.edu/books/nurnberg-funnel). He writes, "[Learners] are too busy learning to make much use of the instruction. This is the paradox of sense making." I can relate to this, and you probably can too. When I'm going through a tutorial, my eyes are scanning for blocks of code because I'm trying to learn by doing. I'm literally too busy learning to read the instructions. @@ -43,13 +43,13 @@ The [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms ![The remote containers extension screenshot from extension gallery](remote-containers-extension.png) -In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you though selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case I add the Azure CLI, Dotnet CLI and Powershell… +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you though selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case, I add the Azure CLI, Dotnet CLI and Powershell… ![Adding a dev container configuration to a Python project](add-dev-container.gif) -This process adds a “.devcontainer” folder to this project with the necessary “Dockerfile” included. It also adds a “devcontainer.json” file, which is a standard for defining aspects of a dev container, like which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. +This process adds a `.devcontainer` folder to this project with the necessary `Dockerfile` included. It also adds a `devcontainer.json` file, which is a standard for defining aspects of a dev container, like which extensions should be installed, which setup commands should be run after container build, etc. Since you have complete control over the environment and its setup, you can automate pretty much everything - including dependency installs, library versions, etc. -In this way, it’s possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. +In this way, it's possible to quite literally hand someone a complete, ready-to-use environment that requires no additional setup steps or triggering of existential crisis over Ruby gems. Some folks are already using a dev container-based approach to get their users up and running quickly with what are otherwise very complex environments. A great example of this is the Laravel framework for PHP. @@ -79,7 +79,7 @@ I specified that our project has a MySQL Server and a Redis Cache, so we actuall These containers are networked together so that we can call the MySQL or Redis cache containers from the app container. -If you connect an interactive terminal to the “sail-8.1/app container”, you’ll see your project in the /var/www/html folder. Because Docker “mounts” the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. +If you connect an interactive terminal to the `sail-8.1/app container`, you'll see your project in the `/var/www/html` folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. ![The file structure of the Laravel project in a container](container-file-structure.png) @@ -136,7 +136,7 @@ For VS Code and Laravel, extensions are suggested in the `devcontainer.json`, bu ## Read less, do more -People don't read. And that should be OK. Laravel's tutorials aren't necessarily shorter than any others, but the important thing is that if you skip to the code and just run the commands, it works. Dev containers make that possible. Now if only we could figure out how to make a dev container for our own [How to use Remote Containers in Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) tutorial... +People don't read. And that should be OK. Laravel's tutorials aren't necessarily shorter than any others, but the important thing is that if you skip to the code and just run the commands, it works. Dev containers make that possible. Now if only we could figure out how to make a dev container for our own [Use a Docker container as a development environment with Visual Studio Code](https://docs.microsoft.com/learn/modules/use-docker-container-dev-env-vs-code/) tutorial... Happy Coding! From c4a3adcb6b9a120f5af927627501c390bef884d2 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Wed, 9 Mar 2022 13:52:42 -0800 Subject: [PATCH 24/46] Add blog post back into TOC --- blogs/2022/03/08/the-tutorial-problem.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 3776bf26ca..0335b2d579 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -1,5 +1,5 @@ --- -Order: +Order: 71 TOCTitle: Solving the Tutorial Problem PageTitle: Solving the Tutorial Problem MetaDescription: How Laravel uses containerized dev environments to make a better tutorial @@ -43,7 +43,7 @@ The [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms ![The remote containers extension screenshot from extension gallery](remote-containers-extension.png) -In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you though selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case, I add the Azure CLI, Dotnet CLI and Powershell… +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you through selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case, I add the Azure CLI, Dotnet CLI and PowerShell… ![Adding a dev container configuration to a Python project](add-dev-container.gif) @@ -79,7 +79,7 @@ I specified that our project has a MySQL Server and a Redis Cache, so we actuall These containers are networked together so that we can call the MySQL or Redis cache containers from the app container. -If you connect an interactive terminal to the `sail-8.1/app container`, you'll see your project in the `/var/www/html` folder. Because Docker "mounts" the project from your machine into the container, any changes you make while developing are reflected in the application when you refresh. +If you connect an interactive terminal to the `sail-8.1/app container`, you'll see your project in the `/var/www/html` folder. Docker "mounts" the project from your machine into the container, so any changes you make while developing are reflected in the application when you refresh. ![The file structure of the Laravel project in a container](container-file-structure.png) From aa71ff6332a5487aa1aead1a1f259b27164f5f73 Mon Sep 17 00:00:00 2001 From: Nouman Rahman Date: Thu, 10 Mar 2022 19:42:46 +0530 Subject: [PATCH 25/46] Fixed angular-tutorial.md `React` section Changed the link of react website to `https://reactjs.org` from `https://facebook.github.io/react` and changed the term `web framework` to `library for building ui` --- docs/nodejs/angular-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nodejs/angular-tutorial.md b/docs/nodejs/angular-tutorial.md index 7775337c2a..8f4714b39e 100644 --- a/docs/nodejs/angular-tutorial.md +++ b/docs/nodejs/angular-tutorial.md @@ -160,7 +160,7 @@ If you'd like to see a full MEAN (MongoDB, Express, Angular, Node.js) stack exam ### React -[React](https://facebook.github.io/react/) is another popular web framework. If you'd like to see an example of React working with VS Code, check out the [Using React in VS Code](/docs/nodejs/reactjs-tutorial.md) tutorial. It will walk you through creating an React application and configuring the `launch.json` file for the JavaScript debugger. +[React](https://reactjs.org) is a library for building ui and it is more minimal than angular. If you'd like to see an example of React working with VS Code, check out the [Using React in VS Code](/docs/nodejs/reactjs-tutorial.md) tutorial. It will walk you through creating an React application and configuring the `launch.json` file for the JavaScript debugger. ## Angular Extensions From 57311b5aff211a61fc6b337b5b735b0e91e02731 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 10 Mar 2022 06:55:52 -0800 Subject: [PATCH 26/46] Change blog title --- blogs/2022/03/08/the-tutorial-problem.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 0335b2d579..4eb0916a7c 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -1,13 +1,13 @@ --- Order: 71 -TOCTitle: Solving the Tutorial Problem -PageTitle: Solving the Tutorial Problem +TOCTitle: The problem with tutorials +PageTitle: The problem with tutorials MetaDescription: How Laravel uses containerized dev environments to make a better tutorial Date: 2022-03-08 Author: Burke Holland --- -# Solving the "Tutorial" problem +# The problem with tutorials March 8, 2022 by Burke Holland, [@burkeholland](https://twitter.com/burkeholland) From 1e4d86b347c06ddb14943fa56f1aee49facff734 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 10 Mar 2022 07:38:04 -0800 Subject: [PATCH 27/46] Small edits --- blogs/2022/03/08/the-tutorial-problem.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/blogs/2022/03/08/the-tutorial-problem.md b/blogs/2022/03/08/the-tutorial-problem.md index 4eb0916a7c..d5d9ff4649 100644 --- a/blogs/2022/03/08/the-tutorial-problem.md +++ b/blogs/2022/03/08/the-tutorial-problem.md @@ -43,7 +43,7 @@ The [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms ![The remote containers extension screenshot from extension gallery](remote-containers-extension.png) -In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you through selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case, I add the Azure CLI, Dotnet CLI and PowerShell… +In order to create a containerized dev environment, you would ordinarily have to know a thing or two about Docker. A lot of people do, but a lot of people **don't** (you can't see me, but my hand is in the air), so the extension tries to abstract the container setup process away as much as possible. I set up a new Python container. A wizard walks you through selecting the base image and Python version. It then gives you the opportunity to add additional software to the image via a picker list. In this case, I add the Azure CLI, Dotnet CLI and PowerShell… ![Adding a dev container configuration to a Python project](add-dev-container.gif) @@ -55,7 +55,7 @@ Some folks are already using a dev container-based approach to get their users u ## The Laravel solution -[Laravel](https://laravel.com/) is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. +[Laravel](https://laravel.com/) is an open-source MVC framework for PHP. It's comprehensive in the sense that it also includes things like an Object Relational Mapper (ORM), direct database access, a packaging system, and more. Laravel can do a lot. And in order to experience it, you really need to have at least a database when you're getting started. Normally this would require the user to install not just PHP, but a database as well - usually MySQL. That's a significant ask when a user is simply trying your framework on for size. Laravel addresses this with containerized dev environments and a tool called [Sail](https://github.com/laravel/sail). To get started from scratch with Laravel, a MySQL Server, and a Redis Cache, you only have to run a single command... @@ -73,7 +73,7 @@ The sample application just runs. No installing PHP. No Laravel. No dependency r ![An example Laravel application running in the browser on localhost](laravel-app.png) -I specified that our project has a MySQL Server and a Redis Cache, so we actually get three containers when the project spins up. We can see that using the [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) extension for VS Code. +I specified that our project has a MySQL Server and a Redis Cache, so we actually get three containers when the project spins up. We can see that using the [Docker extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) for VS Code. ![The Docker extension in VS Code](docker-extension.png) @@ -91,13 +91,13 @@ Support has also been added for the [Remote - Containers](https://marketplace.vi curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash ``` -> Note that if you want to add a devcontainer to an existing Sail/Laravel project, you can do that by running `php artisan sail:install --devcontainer` +> Note that if you want to add a devcontainer to an existing Sail/Laravel project, you can do that by running `php artisan sail:install --devcontainer`. This creates the same project configuration, but will include a `.devcontainer` folder. VS Code will automatically detect that folder and prompt you to reopen the project in a container thereby skipping the required `sail up` step. ![A notification in VS Code saying "Reopen in container"](reopen-in-container-prompt.png) -VS Code attaches to the container, so you are developing **within** the container environment as opposed to your local one. You'll know that because the Remote Indicator in the left-hand corner of VS Code tells you so... +VS Code attaches to the container, so you are developing **within** the container environment as opposed to your local one. You'll know that because the Remote Indicator in the lower left-hand corner of VS Code tells you so... ![The remote indicator in VS Code showing connection to a container](remote-indicator.png) From c1608d07900352a2b9ef4440c38850142210f2c4 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 10 Mar 2022 10:00:00 -0800 Subject: [PATCH 28/46] Mention 1.65.2 release --- release-notes/v1_65.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/release-notes/v1_65.md b/release-notes/v1_65.md index 98dd558d04..3b9a2c8b7e 100644 --- a/release-notes/v1_65.md +++ b/release-notes/v1_65.md @@ -5,12 +5,14 @@ PageTitle: Visual Studio Code February 2022 MetaDescription: Learn what is new in the Visual Studio Code February 2022 Release (1.65) MetaSocialImage: 1_65/release-highlights.png Date: 2022-3-3 -DownloadVersion: 1.65.1 +DownloadVersion: 1.65.2 --- # February 2022 (version 1.65) **Update 1.65.1**: The update addresses these security [issues](https://github.com/microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22February+2022+Recovery+1%22+is%3Aclosed). +**Update 1.65.2**: The update addresses these [issues](https://github.com/microsoft/vscode/issues?q=is%3Aissue+milestone%3A%22February+2022+Recovery+2%22+is%3Aclosed). + --- From 3ef679dedbaff6dcd45f710416005c5a9fb7aac1 Mon Sep 17 00:00:00 2001 From: Nouman Rahman Date: Fri, 11 Mar 2022 20:16:56 +0530 Subject: [PATCH 29/46] Fix the .NET Core tutorial Fixed the .NET Core tutorial to say ''fast and modular platform for creating many different types of applications" instead of "fast and modular platform for creating server apps" --- docs/languages/dotnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/languages/dotnet.md b/docs/languages/dotnet.md index c02e7ae050..598415f083 100644 --- a/docs/languages/dotnet.md +++ b/docs/languages/dotnet.md @@ -9,7 +9,7 @@ MetaDescription: Get started writing and debugging .NET Core apps with Visual St --- # Using .NET Core in Visual Studio Code -[.NET Core](https://docs.microsoft.com/dotnet/core) provides a fast and modular platform for creating server apps that run on Windows, Linux, and macOS. Use Visual Studio Code with the C# and F# extensions to get a powerful editing experience with [C# IntelliSense](https://docs.microsoft.com/visualstudio/ide/visual-csharp-intellisense), F# IntelliSense (smart code completion), and debugging. +[.NET Core](https://docs.microsoft.com/dotnet/core) provides a fast and modular platform for creating many different types of applications that run on Windows, Linux, and macOS. Use Visual Studio Code with the C# and F# extensions to get a powerful editing experience with [C# IntelliSense](https://docs.microsoft.com/visualstudio/ide/visual-csharp-intellisense), F# IntelliSense (smart code completion), and debugging. ## Prerequisites From 12cf7b28c409096387db15ee73f12fb7dc7b94b3 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Fri, 11 Mar 2022 17:11:39 -0800 Subject: [PATCH 30/46] Update other React links --- docs/nodejs/angular-tutorial.md | 2 +- docs/nodejs/reactjs-tutorial.md | 2 +- release-notes/vMarch.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/nodejs/angular-tutorial.md b/docs/nodejs/angular-tutorial.md index 8f4714b39e..372025ab1f 100644 --- a/docs/nodejs/angular-tutorial.md +++ b/docs/nodejs/angular-tutorial.md @@ -160,7 +160,7 @@ If you'd like to see a full MEAN (MongoDB, Express, Angular, Node.js) stack exam ### React -[React](https://reactjs.org) is a library for building ui and it is more minimal than angular. If you'd like to see an example of React working with VS Code, check out the [Using React in VS Code](/docs/nodejs/reactjs-tutorial.md) tutorial. It will walk you through creating an React application and configuring the `launch.json` file for the JavaScript debugger. +[React](https://reactjs.org) is a library for building user interfaces and it is more minimal than angular. If you'd like to see an example of React working with VS Code, check out the [Using React in VS Code](/docs/nodejs/reactjs-tutorial.md) tutorial. It will walk you through creating an React application and configuring the `launch.json` file for the JavaScript debugger. ## Angular Extensions diff --git a/docs/nodejs/reactjs-tutorial.md b/docs/nodejs/reactjs-tutorial.md index 734af8cd2b..3b7b978ef0 100644 --- a/docs/nodejs/reactjs-tutorial.md +++ b/docs/nodejs/reactjs-tutorial.md @@ -10,7 +10,7 @@ MetaSocialImage: /assets/images/nodejs_javascript_vscode.png --- # Using React in Visual Studio Code -[React](https://facebook.github.io/react/) is a popular JavaScript library developed by Facebook for building web application user interfaces. The Visual Studio Code editor supports React.js IntelliSense and code navigation out of the box. +[React](https://reactjs.org) is a popular JavaScript library developed by Facebook for building user interfaces. The Visual Studio Code editor supports React.js IntelliSense and code navigation out of the box. ![Welcome to React](images/reactjs/welcome-to-react.png) diff --git a/release-notes/vMarch.md b/release-notes/vMarch.md index 6c2a152ab2..8eeb84bfbc 100644 --- a/release-notes/vMarch.md +++ b/release-notes/vMarch.md @@ -63,7 +63,7 @@ To make it easy to distinguish between diagnostics from external linters and the ### IntelliSense when using ES6 import statements in React Native -Previously you did not get IntelliSense when using ES6 style import statements in **React Native** as used in the [getting started guide](https://facebook.github.io/react-native/docs/getting-started.html#quick-start). +Previously you did not get IntelliSense when using ES6 style import statements in **React Native** as used in the [getting started guide](https://reactnative.dev/docs/getting-started). In the snippet, below you get no IntelliSense for `React`: From f5167bb6ecdd4389aa7622f32cfa4c2ff517f8c6 Mon Sep 17 00:00:00 2001 From: Martin Bjeldbak Madsen Date: Mon, 14 Mar 2022 00:24:24 +1000 Subject: [PATCH 31/46] Documentation: fix capitalization of PostgreSQL --- docs/remote/create-dev-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/remote/create-dev-container.md b/docs/remote/create-dev-container.md index a6028747d6..69cfd4cbb5 100644 --- a/docs/remote/create-dev-container.md +++ b/docs/remote/create-dev-container.md @@ -422,7 +422,7 @@ The following are dev container definitions that use Docker Compose: * [Existing Docker Compose](https://aka.ms/vscode-remote/samples/existing-docker-compose) - Includes a set of files that you can drop into an existing project that will reuse a `docker-compose.yml` file in the root of your project. * [Node.js & MongoDB](https://aka.ms/vscode-remote/samples/node-mongo) - A Node.js container that connects to a Mongo DB in a different container. -* [Python & PostgreSQL](https://aka.ms/vscode-remote/samples/python-postgres) - A Python container that connects to PostGreSQL in a different container. +* [Python & PostgreSQL](https://aka.ms/vscode-remote/samples/python-postgres) - A Python container that connects to PostgreSQL in a different container. * [Docker-from-Docker Compose](https://aka.ms/vscode-remote/samples/docker-from-docker-compose) - Includes the Docker CLI and illustrates how you can use it to access your local Docker install from inside a dev container by volume mounting the Docker Unix socket. Congratulations! You've now configured a dev container in Visual Studio Code. Continue reading to learn how to share container configurations among teammates and various projects. From 13b34e48b6a9bbdca33f72dd367322b422fde00f Mon Sep 17 00:00:00 2001 From: gregvanl Date: Sun, 13 Mar 2022 21:41:38 -0700 Subject: [PATCH 32/46] Update Settings topic Fixes #5136 --- .../images/settings/accounts-context-menu.png | 3 + .../images/settings/activity-bar-hidden.png | 3 + .../images/settings/activity-bar.png | 3 + .../settings/clear-search-input-button.png | 3 + .../settings/color-customization-example.png | 3 + .../settings/cpp-extension-settings.png | 3 + .../settings/edit-in-settings-json-link.png | 3 + .../images/settings/modified-settings.png | 3 + .../settings/more-actions-context-menu.png | 3 + .../settings/python-feature-contributions.png | 3 + .../images/settings/search-for-activity.png | 3 + .../settings/settings-editor-filters.png | 3 + .../settings-editor-workspace-tab.png | 3 + .../settings/settings-json-in-editor.png | 3 + .../settings/settings-json-intellisense.png | 3 + docs/getstarted/settings.md | 200 ++++++++++++++---- docs/getstarted/themes.md | 4 +- docs/getstarted/userinterface.md | 2 +- 18 files changed, 207 insertions(+), 44 deletions(-) create mode 100644 docs/getstarted/images/settings/accounts-context-menu.png create mode 100644 docs/getstarted/images/settings/activity-bar-hidden.png create mode 100644 docs/getstarted/images/settings/activity-bar.png create mode 100644 docs/getstarted/images/settings/clear-search-input-button.png create mode 100644 docs/getstarted/images/settings/color-customization-example.png create mode 100644 docs/getstarted/images/settings/cpp-extension-settings.png create mode 100644 docs/getstarted/images/settings/edit-in-settings-json-link.png create mode 100644 docs/getstarted/images/settings/modified-settings.png create mode 100644 docs/getstarted/images/settings/more-actions-context-menu.png create mode 100644 docs/getstarted/images/settings/python-feature-contributions.png create mode 100644 docs/getstarted/images/settings/search-for-activity.png create mode 100644 docs/getstarted/images/settings/settings-editor-filters.png create mode 100644 docs/getstarted/images/settings/settings-editor-workspace-tab.png create mode 100644 docs/getstarted/images/settings/settings-json-in-editor.png create mode 100644 docs/getstarted/images/settings/settings-json-intellisense.png diff --git a/docs/getstarted/images/settings/accounts-context-menu.png b/docs/getstarted/images/settings/accounts-context-menu.png new file mode 100644 index 0000000000..c197e08ced --- /dev/null +++ b/docs/getstarted/images/settings/accounts-context-menu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fd7a209d1578468e3163a5b72bdc1dffdb731691e289f86f61b0332ab0461543 +size 21771 diff --git a/docs/getstarted/images/settings/activity-bar-hidden.png b/docs/getstarted/images/settings/activity-bar-hidden.png new file mode 100644 index 0000000000..6bb667698e --- /dev/null +++ b/docs/getstarted/images/settings/activity-bar-hidden.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b042300347c7a2734c6fb6c0657f8497e4a786eb8e576e957e7c7faee41759bd +size 77338 diff --git a/docs/getstarted/images/settings/activity-bar.png b/docs/getstarted/images/settings/activity-bar.png new file mode 100644 index 0000000000..a0ce64b911 --- /dev/null +++ b/docs/getstarted/images/settings/activity-bar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9fede849d1f6c29ead37407ac927aaa4a92b0a18298e185ed7261d10099b9319 +size 98754 diff --git a/docs/getstarted/images/settings/clear-search-input-button.png b/docs/getstarted/images/settings/clear-search-input-button.png new file mode 100644 index 0000000000..9233b72a0d --- /dev/null +++ b/docs/getstarted/images/settings/clear-search-input-button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1bde5c723692ba1a7151fdc155be57a53e8d882c825ab9f0bcb503c58d42dad1 +size 7694 diff --git a/docs/getstarted/images/settings/color-customization-example.png b/docs/getstarted/images/settings/color-customization-example.png new file mode 100644 index 0000000000..3aacb725d5 --- /dev/null +++ b/docs/getstarted/images/settings/color-customization-example.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d460b8fc5780b4bffa1fc24abaaa14bbc4ca41ed569981e780e6bb20a455018e +size 74300 diff --git a/docs/getstarted/images/settings/cpp-extension-settings.png b/docs/getstarted/images/settings/cpp-extension-settings.png new file mode 100644 index 0000000000..abf48a3cf3 --- /dev/null +++ b/docs/getstarted/images/settings/cpp-extension-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c88844ee5b55c3a7c3d809e75467d2181dfadeac2bff7097a6df93bf2f39355 +size 100602 diff --git a/docs/getstarted/images/settings/edit-in-settings-json-link.png b/docs/getstarted/images/settings/edit-in-settings-json-link.png new file mode 100644 index 0000000000..5f741e3145 --- /dev/null +++ b/docs/getstarted/images/settings/edit-in-settings-json-link.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7fb5fe739836abf1a782c3f85e1b1fb53144c41072d6b87cb21a61ad3cad6d0d +size 20263 diff --git a/docs/getstarted/images/settings/modified-settings.png b/docs/getstarted/images/settings/modified-settings.png new file mode 100644 index 0000000000..fb6b6e1383 --- /dev/null +++ b/docs/getstarted/images/settings/modified-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:beaafdef59bfaa924c7e9e33999381f207473b666c685c34eface06fccb1c54f +size 67376 diff --git a/docs/getstarted/images/settings/more-actions-context-menu.png b/docs/getstarted/images/settings/more-actions-context-menu.png new file mode 100644 index 0000000000..9ca7c6119d --- /dev/null +++ b/docs/getstarted/images/settings/more-actions-context-menu.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3c1a6d19f237f7e6bf9807efcc6d2cfd271d1b372a586d0785be03b518680d74 +size 49092 diff --git a/docs/getstarted/images/settings/python-feature-contributions.png b/docs/getstarted/images/settings/python-feature-contributions.png new file mode 100644 index 0000000000..b79ceebc6d --- /dev/null +++ b/docs/getstarted/images/settings/python-feature-contributions.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:76a3eceede539044c59daf7f552b292952e3b35ced97bffb947e78c2fc97d8ef +size 169546 diff --git a/docs/getstarted/images/settings/search-for-activity.png b/docs/getstarted/images/settings/search-for-activity.png new file mode 100644 index 0000000000..c4e37342d3 --- /dev/null +++ b/docs/getstarted/images/settings/search-for-activity.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1a9196cf044e4e845212829370c57016655981536c14536712f35295cf3557c2 +size 104250 diff --git a/docs/getstarted/images/settings/settings-editor-filters.png b/docs/getstarted/images/settings/settings-editor-filters.png new file mode 100644 index 0000000000..c161bdf078 --- /dev/null +++ b/docs/getstarted/images/settings/settings-editor-filters.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:98af0b0ad0d056ff3e1254358aa6cb7e763fb4b505bc0ba4e645abf27bf643df +size 49199 diff --git a/docs/getstarted/images/settings/settings-editor-workspace-tab.png b/docs/getstarted/images/settings/settings-editor-workspace-tab.png new file mode 100644 index 0000000000..396293128d --- /dev/null +++ b/docs/getstarted/images/settings/settings-editor-workspace-tab.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:624a143736c8db038f5098a07cae4b0b98cce3a45f3ee9f9516a34b44255583a +size 38689 diff --git a/docs/getstarted/images/settings/settings-json-in-editor.png b/docs/getstarted/images/settings/settings-json-in-editor.png new file mode 100644 index 0000000000..36a330937f --- /dev/null +++ b/docs/getstarted/images/settings/settings-json-in-editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc29b60a1ff1424811bfbf8e95d739e73103bfe821e8b78341b6073470534c60 +size 32842 diff --git a/docs/getstarted/images/settings/settings-json-intellisense.png b/docs/getstarted/images/settings/settings-json-intellisense.png new file mode 100644 index 0000000000..0aa5d2b520 --- /dev/null +++ b/docs/getstarted/images/settings/settings-json-intellisense.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:101478ee73265a0b5f27bef7d2d8b99f3fa4ee492e8992636ab7d9c95add93dc +size 115158 diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md index 2a6ce94c97..d83a7b5120 100644 --- a/docs/getstarted/settings.md +++ b/docs/getstarted/settings.md @@ -11,43 +11,37 @@ MetaDescription: How to modify Visual Studio Code User and Workspace Settings. You can configure Visual Studio Code to your liking through its various settings. Nearly every part of VS Code's editor, user interface, and functional behavior has options you can modify. -![VS Code Settings editor](images/settings/hero.png) - VS Code provides two different scopes for settings: * **User Settings** - Settings that apply globally to any instance of VS Code you open. * **Workspace Settings** - Settings stored inside your workspace and only apply when the workspace is opened. -Workspace settings override user settings. Workspace settings are specific to a project and can be shared across developers on a project. - ->**Note**: You cannot use the Settings editor to create a workspace setting that matches the setting's default value. If you want your workspace to enforce that a particular setting has its default value, even when somebody has configured that setting as a user setting, you must add it to the workspace settings file manually. +In this article, we'll first describe user settings as these are your personal settings for customizing VS Code. Later we'll cover [Workspace Settings](#workspace-settings), which will be specific to the project you're working on. ->**Note**: A VS Code "workspace" is usually just your project root folder. Workspace settings as well as [debugging](/docs/editor/debugging.md) and [task](/docs/editor/tasks.md) configurations are stored at the root in a `.vscode` folder. You can also have more than one root folder in a VS Code workspace through a feature called [Multi-root workspaces](/docs/editor/multi-root-workspaces.md). You can learn more in the [What is a VS Code "workspace"?](/docs/editor/workspaces.md) article. +## Settings editor -## Creating User and Workspace Settings +To modify user settings, you'll use the Settings editor to review and change VS Code settings. -To open your user and workspace settings, use the following VS Code menu command: +To open the Settings editor, use the following VS Code menu command: * On Windows/Linux - **File** > **Preferences** > **Settings** * On macOS - **Code** > **Preferences** > **Settings** You can also open the Settings editor from the **Command Palette** (`kb(workbench.action.showCommands)`) with **Preferences: Open Settings** or use the keyboard shortcut (`kb(workbench.action.openSettings)`). -In the example below, the side bar location and file icon theme have been changed. +When you open the Settings editor, you can search and discover the settings you are looking for. When you search using the Search bar, it will not only show and highlight the settings matching your criteria, but also filter out those which are not matching. This makes finding settings quick and easy. -![Modified settings in the Settings editor showing blue vertical bars to the left of them](images/settings/settings-modified.png) - -Changes to settings are reloaded by VS Code as you change them. Modified settings are now indicated with a _blue line_ similar to modified lines in the editor. The gear icon opens a context menu with options to reset the setting to its default value as well as copy setting as JSON. +![Filtering settings by searching in the Settings editor](images/settings/settings-search.png) ->**Note:** Workspace settings are useful for sharing project specific settings across a team. +In the example below, the Side Bar location and file icon theme have been changed. -## Settings editor +![Modified settings in the Settings editor showing blue vertical bars to the left of them](images/settings/settings-modified.png) -When you open the settings editor, you can search and discover settings you are looking for. When you search using the Search bar, it will not only show and highlight the settings matching your criteria, but also filter out those which are not matching. This makes finding settings quick and easy. +Changes to settings are reloaded by VS Code as you change them. Modified settings are indicated with a **blue line** similar to modified lines in the editor. -![Filtering settings by searching in the Settings editor](images/settings/settings-search.png) +The gear icon (**More Actions...** `kb(settings.action.showContextMenu)`) opens a context menu with options to reset the setting to its default value as well as copy the setting ID or JSON name-value pair. -**Note**: VS Code extensions can also add their own custom settings and they will be visible under an **Extensions** section. +![Settings edit gear context menu](images/settings/more-actions-context-menu.png) ### Edit settings @@ -57,15 +51,102 @@ Each setting can be edited by either a **checkbox**, an **input** or by a **drop ### Settings groups -Default settings are represented in groups so that you can navigate them easily. It has a **Commonly Used** group at the top, which shows popular customizations. +Settings are represented in groups so that you can navigate them easily. It has a **Commonly Used** group at the top, which shows popular customizations. + +Below the Source Control Management (SCM) settings are focused by selecting **SCM** in the tree view. ![Settings editor with the SCM section of the table of contents selected](images/settings/settings-groups.png) -Below is a [copy of the default settings](/docs/getstarted/settings.md#default-settings) that come with VS Code. +**Note**: VS Code extensions can also add their own custom settings and they will be visible under an **Extensions** section. + +## Changing a setting + +As an example, let's hide the Activity Bar from VS Code. The Activity Bar is the wide border on the left with various icons for different views such as the File Explorer, Search, Source Control, and Extensions. You might want to hide the Activity Bar to give the editor a little more room and if you prefer to open views via the **View** menu or Command Palette. + +![Activity Bar display on the left of the editor](images/settings/activity-bar.png) + +Open the Settings Editor (`kb((workbench.action.openSettings)`) and type 'activity' in the Search bar. You should see 5 settings. + +![Settings editor with 'activity' in the Search bar with 5 settings](images/settings/search-for-activity.png) + +You can further limit the scope to just those settings under the **Appearance** group in the left side tree. There should not be just three settings. + +You can now check and uncheck the **Workbench** > **Activity Bar: Visible** setting to hide and unhide the Activity Bar. Notice that when you have changed the setting from the default you see the blue line to the left. You can always reset a setting to the default value via the gear context menu **Reset Settings** command. + +![Activity Bar: Visible unchecked and Activity Bar is hidden](images/settings/activity-bar-hidden.png) + +## Settings editor filters + +The Settings editor Search bar has several filters to make it easier to manage your settings. + +### Modified settings + +To check which settings you have changed, there is a `@modified` filter in the Search bar. This can be useful if you have forgotten whether you changed a setting or if the editor is not behaving as you expect because you accidentally modified a setting. + +![Settings editor with @modified filter showing four changed settings](images/settings/modified-settings.png) + +### Other filters + +There are several other handy filters for searching settings. + +![Setting editor @ tag filter dropdown](images/settings/settings-editor-filters.png) + +Here are some of the filters available: + +* `@ext` - Settings specific to an extension. You provide the extension ID such as `@ext:ms-python.python`. +* `@feature` - Settings specific to a **Features** sub-group. For example, `@feature:explorer` shows settings of the File Explorer. +* `@id` - Find a setting based on the setting ID. For example, `@id:workbench.activityBar.visible`. +* `@tag` - Settings specific to a system of VS Code. For example, `@tag:workspaceTrust` for settings related to [Workspace Trust](/docs/editor/workspace-trust.md) + +The Search bar remembers your settings search queries and supports Undo/Redo (`kb(undo)`/`kb(redo`)). You can quickly clear a search term or filter with the **Clear Settings Search Input** button at the right of the Search bar. + +![Clear Settings Search Input button in the right of the Settings editor](images/settings/clear-search-input-button.png) + +## Extension settings + +Installed VS Code extensions can also contribute their own settings, which you can review under the **Extensions** section of the Settings editor. + +![C++ extension settings in the Settings editor](images/settings/cpp-extension-settings.png) + +You can also review an extension's settings from the Extensions view (`kb(workbench.view.extensions)`) by selecting the extension and reviewing the **Feature Contributions** tab. + +![Python extension Settings list under Feature Contributions tab](images/settings/python-feature-contributions.png) + +Extension authors can learn more about adding custom settings in the `configuration` [contribution point documentation](/api/references/contribution-points.md#contributes.configuration). + +## settings.json + +The Settings editor is the UI that lets you review and modify setting values that are stored in a `settings.json` file. You can review and edit this file directly by opening it in the editor with the **Preferences: Open Settings (JSON)** command. Settings are written as JSON by specifying the settings ID and value. + +![User settings.json open in the editor](images/settings/settings-json-in-editor.png) + +`settings.json` has full IntelliSense with smart completions for settings and values and hovers for descriptions. Errors due to incorrect setting names or JSON formatting are also highlighted. + +![IntelliSense for settings.json open in the editor](images/settings/settings-json-intellisense.png) + +Some settings can only be edited in `settings.json` such as **Workbench: Color Customizations** and show a **Edit in settings.json** link in the Settings editor. + +![Workbench: Color Customizations setting with Edit in settings.json link](images/settings/edit-in-settings-json-link.png) + +As an example, lets change the editor line number color. Click the **Edit in settings.json** link and add the following JSON: + +```json + "workbench.colorCustomizations": { + "editorLineNumber.foreground": "#00ff00" + } +``` + +Here the line numbers in the editor for the `settings.json` file are now green. + +![settings.json editor with green line numbers](images/settings/color-customization-example.png) -## Settings file locations +Remove the `workbench.colorCustomizations` setting code block to return the line number color to the default. -By default VS Code shows the Settings editor, but you can still edit the underlying `settings.json` file by using the **Open Settings (JSON)** command or by changing your default settings editor with the `workbench.settings.editor` setting. +>**Note**: The example above changes the editor line number for all [Color Themes](/docs/getstarted/themes.md), but you can tune colors per [specific Color Theme](/docs/getstarted/themes.md#customizing-a-color-theme) or even [create your own Color Theme](/api/extension-guides/color-theme.md#create-a-new-color-theme) extension. + +If you prefer to always work directly with `settings.json`, you can set `"workbench.settings.editor": "json"` so that **File** > **Preferences** > **Settings** and the keybinding `kb(workbench.action.openSettings)` always opens the `settings.json` file and not the Setting editor UI. + +### Settings file locations Depending on your platform, the user settings file is located here: @@ -73,13 +154,37 @@ Depending on your platform, the user settings file is located here: * **macOS** `$HOME/Library/Application\ Support/Code/User/settings.json` * **Linux** `$HOME/.config/Code/User/settings.json` +### Reset all settings + +While you can reset settings individually via the Settings editor **Reset Setting** command, you can reset all changed settings by opening `settings.json` and deleting the entries between the braces `{}`. Be careful since there will be no way to recover your previous setting values. + +## Workspace Settings + +Workspace settings are specific to a project and can be shared across developers on a project. Workspace settings override user settings. + +>**Note**: A VS Code "workspace" is usually just your project root folder. Workspace settings as well as [debugging](/docs/editor/debugging.md) and [task](/docs/editor/tasks.md) configurations are stored at the root in a `.vscode` folder. You can also have more than one root folder in a VS Code workspace through a feature called [Multi-root workspaces](/docs/editor/multi-root-workspaces.md). You can learn more in the [What is a VS Code "workspace"?](/docs/editor/workspaces.md) article. + +You can edit via the Settings editor **Workspace** tab or open that tab directly with the **Preferences: Open Workspace Settings** command. + +![Settings editor with Workspace tab highlighted](images/settings/settings-editor-workspace-tab.png) + +All features of the Settings editor such as settings groups, search, and filtering behave the same for Workspace settings. Not all User settings are available as Workspace settings. For example, application-wide settings related to updates and security can not be overridden by Workspace settings. + +### Workspace settings.json location + +Similar to User Settings, Workspace Settings are also stored in a `settings.json` file, which you can edit directly via the **Preferences: Open Workspace Settings (JSON)** command. + The workspace settings file is located under the `.vscode` folder in your root folder. >**Note:** In case of a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md#settings), workspace settings are located inside the workspace configuration file. +When you add Workspace Settings `settings.json` file to your project or source control, the default settings for the project will be shared by all users of that project + +>**Note**: You cannot use the Settings editor to create a workspace setting that matches the setting's default value. If you want your workspace to enforce that a particular setting has its default value, even when somebody has configured that setting as a user setting, you must add it to the workspace `settings.json` file manually. + ## Language-specific editor settings -To customize your editor by language, run the global command **Preferences: Configure Language Specific Settings** (command ID: `workbench.action.configureLanguageBasedSettings`) from the **Command Palette** (`kb(workbench.action.showCommands)`) which opens the language picker. Select the language you want, which then opens your user `settings.json` with the language entry where you can add applicable settings. +You can also customize your editor by programming language, which can be useful when language conventions differ. To modify settings for a language, run the global command **Preferences: Configure Language Specific Settings** (command ID: `workbench.action.configureLanguageBasedSettings`) from the **Command Palette** (`kb(workbench.action.showCommands)`), which opens the language picker. Select the language you want, which then opens your user `settings.json` with the language entry where you can add applicable settings. ![Configure language-specific settings command typed up in the Command Palette](images/settings/pref-config-lang-settings.png) @@ -123,6 +228,7 @@ Configurations can be overridden at multiple levels by the different setting sco * User settings - Apply globally to all VS Code instances. * Workspace setting - Apply to the open folder or workspace and override User settings. * Workspace Folder settings - Apply to a specific folder of a [multi-root workspace](/docs/editor/multi-root-workspaces.md). Override User and Workspace settings. +* Language-specific editor settings - Override Workspace settings. Setting values can be of various types: @@ -177,9 +283,38 @@ Here is the list of settings not supported in workspace settings: The first time you open a workspace that defines any of these settings, VS Code will warn you and then always ignore the values after that. +## Settings Sync + +You can share your user settings across your VS Code instances with the [Settings Sync](/docs/editor/settings-sync.md) feature. This feature lets you share settings, keyboard shortcuts, and installed extensions across your VS Code installs on various machines. You can enable Settings Sync via the **Turn on Settings Sync** command on the right of the Settings editor or on the **Accounts** Activity Bar context menu. + +![Turn on Settings Sync command in the Accounts Activity Bar menu](images/settings/accounts-context-menu.png) + +You can learn more about turning on and configuring Settings Sync in the [Settings Sync](/docs/editor/settings-sync.md) user guide. + +## Common questions + +### VS Code says "Unable to write settings." + +If you try to change a setting (for example turning on Auto Save or selecting a new Color Theme) and you see "Unable to write into user settings. Please open user settings to correct errors/warnings in it and try again.", it means your `settings.json` file is ill-formed or has errors. The error can be as simple as a missing comma or incorrect setting value. Open the `settings.json` file with the **Preferences: Open Settings (JSON)** command and you should see the error highlighted with red squiggles. + +### How can I reset my user settings? + +The easiest way to reset VS Code back to the default settings is to clear your user `settings.json` file. You can open the `settings.json` file with the **Preferences: Open Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). Once the file is open in an editor, delete everything between the two curly braces `{}`, save the file, and VS Code will go back to using the default values. + +### When does it make sense to use workspace settings? + +If you're using a workspace that needs custom settings but you don't want to apply them to your other VS Code projects. A good example is language-specific linting rules. + +### Where can I find extension settings? + +In general, VS Code extensions store their settings in your user or workspaces settings files and they are available through the Settings editor UI (**Preferences: Open Settings (UI)** - `kb(workbench.action.openSettings)`) or directly in the `settings.json` file (**Preferences: Open Settings (JSON)**). Searching by the extension name (for example `gitlens` or `python`) can help filter down settings to just those contributed by an extension. + ## Default settings -Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor. +Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor or see a read-only version of the `defaultSettings.json` via **Preferences: Open Default Settings (JSON)**. + +
+Click to view Default settings ```json { @@ -4052,21 +4187,4 @@ Below are the Visual Studio Code default settings and their values. You can also "npm.scriptExplorerExclude": [] } ``` - -## Common questions - -### VS Code says "Unable to write settings." - -If you try to change a setting (for example turning on Auto Save or selecting a new Color Theme) and you see "Unable to write settings. Please open User Settings to correct errors/warnings in the file and try again.", it means your `settings.json` file is ill-formed or has errors. The errors can be as simple as a missing comma or setting value. Open the Settings editor **File** > **Preferences** > **Settings** (**Code** > **Preferences** > **Settings** on macOS) (`kb(workbench.action.openSettings)`) and you should see the error highlighted with red squiggles. - -### How can I reset my user settings? - -The easiest way to reset VS Code back to the default settings is to clear your user `settings.json` file. You can open the `settings.json` file with the **Preferences: Open Settings (JSON)** command in the Command Palette (`kb(workbench.action.showCommands)`). Once the file is open in an editor, delete everything between the two curly braces, save the file, and VS Code will go back to using the default values. - -### When does it make sense to use workspace settings? - -If you're using a workspace that needs custom settings but you don't want to apply them to your other VS Code projects. A good example is language-specific linting rules. - -### Where can I find extension settings? - -In general, VS Code extensions store their settings in your user or workspaces settings files and they are available through the Settings editor UI (**Preferences: Open Settings (UI)** - `kb(workbench.action.openSettings)`) or directly in the `settings.json` file (**Preferences: Open Settings (JSON)**). Searching by the extension name (for example `gitlens` or `python`) can help filter down settings to just those contributed by an extension. +
diff --git a/docs/getstarted/themes.md b/docs/getstarted/themes.md index 10d52efeb9..ee9aa21f48 100644 --- a/docs/getstarted/themes.md +++ b/docs/getstarted/themes.md @@ -29,7 +29,7 @@ The active color theme is stored in your user [settings](/docs/getstarted/settin "workbench.colorTheme": "Default Dark+" ``` -> **Tip:** By default, the theme is stored in your user settings and applies globally to all workspaces. You can also configure a workspace specific theme. To do so, set a theme in the Workspace [settings](/docs/getstarted/settings.md#creating-user-and-workspace-settings). +> **Tip:** By default, the theme is stored in your user settings and applies globally to all workspaces. You can also configure a workspace specific theme. To do so, set a theme in the Workspace [settings](/docs/getstarted/settings.md#workspace-settings). ## Color Themes from the Marketplace @@ -74,6 +74,7 @@ To customize a specific theme only, use the following syntax: ``` If a customization applies to more than one themes, you can name multiple themes or use `*` as wildcard at the beginning and the end of the name: + ```json "workbench.colorCustomizations": { "[Abyss][Red]": { @@ -85,7 +86,6 @@ If a customization applies to more than one themes, you can name multiple themes } ``` - ### Editor syntax highlighting To tune the editor's syntax highlighting colors, use `editor.tokenColorCustomizations` in your user [settings](/docs/getstarted/settings.md) `settings.json` file: diff --git a/docs/getstarted/userinterface.md b/docs/getstarted/userinterface.md index 829969c562..e3079311a5 100644 --- a/docs/getstarted/userinterface.md +++ b/docs/getstarted/userinterface.md @@ -198,7 +198,7 @@ You can also hide the Menu Bar on Windows and Linux with the **View** > **Toggle ### Settings -Most editor configurations are kept in settings which can be modified directly. You can set options globally through user settings or per project/folder through workspace settings. Settings values are kept in a `settings.json` [file](/docs/getstarted/settings.md#settings-file-locations). +Most editor configurations are kept in settings which can be modified directly. You can set options globally through user settings or per project/folder through workspace settings. Settings values are kept in a `settings.json` [file](/docs/getstarted/settings.md#settingsjson). * Select **File** > **Preferences** > **Settings** (or press `kb(workbench.action.openSettings)`) to edit the user `settings.json` file. * To edit workspace settings, select the **WORKSPACE SETTINGS** tab to edit the workspace `settings.json` file. From 97c2bf65ce5ec38af587dd5109816381246b3101 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Mon, 14 Mar 2022 13:18:32 -0700 Subject: [PATCH 33/46] Add workspace settings.json location image --- .../settings/settings-json-under-vscode.png | 3 +++ docs/getstarted/settings.md | 18 ++++++++++++------ 2 files changed, 15 insertions(+), 6 deletions(-) create mode 100644 docs/getstarted/images/settings/settings-json-under-vscode.png diff --git a/docs/getstarted/images/settings/settings-json-under-vscode.png b/docs/getstarted/images/settings/settings-json-under-vscode.png new file mode 100644 index 0000000000..0390c1eb12 --- /dev/null +++ b/docs/getstarted/images/settings/settings-json-under-vscode.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0774002816a73e78c25d316d0f232e8fc4391a6d80596673b41982351a64f0a7 +size 99010 diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md index d83a7b5120..1e7db35216 100644 --- a/docs/getstarted/settings.md +++ b/docs/getstarted/settings.md @@ -71,10 +71,12 @@ Open the Settings Editor (`kb((workbench.action.openSettings)`) and type 'activi You can further limit the scope to just those settings under the **Appearance** group in the left side tree. There should not be just three settings. -You can now check and uncheck the **Workbench** > **Activity Bar: Visible** setting to hide and unhide the Activity Bar. Notice that when you have changed the setting from the default you see the blue line to the left. You can always reset a setting to the default value via the gear context menu **Reset Settings** command. +You can now check and uncheck the **Workbench** > **Activity Bar: Visible** setting to hide and unhide the Activity Bar. Notice that when you have changed the setting from the default, you see the blue line to the left. ![Activity Bar: Visible unchecked and Activity Bar is hidden](images/settings/activity-bar-hidden.png) +You can always reset a setting to the default value via the gear context menu **Reset Settings** command. + ## Settings editor filters The Settings editor Search bar has several filters to make it easier to manage your settings. @@ -98,7 +100,7 @@ Here are some of the filters available: * `@id` - Find a setting based on the setting ID. For example, `@id:workbench.activityBar.visible`. * `@tag` - Settings specific to a system of VS Code. For example, `@tag:workspaceTrust` for settings related to [Workspace Trust](/docs/editor/workspace-trust.md) -The Search bar remembers your settings search queries and supports Undo/Redo (`kb(undo)`/`kb(redo`)). You can quickly clear a search term or filter with the **Clear Settings Search Input** button at the right of the Search bar. +The Search bar remembers your settings search queries and supports Undo/Redo (`kb(undo)`/`kb(redo)`). You can quickly clear a search term or filter with the **Clear Settings Search Input** button at the right of the Search bar. ![Clear Settings Search Input button in the right of the Settings editor](images/settings/clear-search-input-button.png) @@ -112,15 +114,15 @@ You can also review an extension's settings from the Extensions view (`kb(workbe ![Python extension Settings list under Feature Contributions tab](images/settings/python-feature-contributions.png) -Extension authors can learn more about adding custom settings in the `configuration` [contribution point documentation](/api/references/contribution-points.md#contributes.configuration). +Extension authors can learn more about adding custom settings in the [configuration contribution point documentation](/api/references/contribution-points.md#contributes.configuration). ## settings.json -The Settings editor is the UI that lets you review and modify setting values that are stored in a `settings.json` file. You can review and edit this file directly by opening it in the editor with the **Preferences: Open Settings (JSON)** command. Settings are written as JSON by specifying the settings ID and value. +The Settings editor is the UI that lets you review and modify setting values that are stored in a `settings.json` file. You can review and edit this file directly by opening it in the editor with the **Preferences: Open Settings (JSON)** command. Settings are written as JSON by specifying the setting ID and value. ![User settings.json open in the editor](images/settings/settings-json-in-editor.png) -`settings.json` has full IntelliSense with smart completions for settings and values and hovers for descriptions. Errors due to incorrect setting names or JSON formatting are also highlighted. +The `settings.json` file has full IntelliSense with smart completions for settings and values and description hovers. Errors due to incorrect setting names or JSON formatting are also highlighted. ![IntelliSense for settings.json open in the editor](images/settings/settings-json-intellisense.png) @@ -128,6 +130,8 @@ Some settings can only be edited in `settings.json` such as **Workbench: Color C ![Workbench: Color Customizations setting with Edit in settings.json link](images/settings/edit-in-settings-json-link.png) +### Changing settings.json + As an example, lets change the editor line number color. Click the **Edit in settings.json** link and add the following JSON: ```json @@ -176,6 +180,8 @@ Similar to User Settings, Workspace Settings are also stored in a `settings.json The workspace settings file is located under the `.vscode` folder in your root folder. +![The File Explorer displaying settings.json under the .vscode folder](images/settings/settings-json-under-vscode.png) + >**Note:** In case of a [Multi-root Workspace](/docs/editor/multi-root-workspaces.md#settings), workspace settings are located inside the workspace configuration file. When you add Workspace Settings `settings.json` file to your project or source control, the default settings for the project will be shared by all users of that project @@ -314,7 +320,7 @@ In general, VS Code extensions store their settings in your user or workspaces s Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor or see a read-only version of the `defaultSettings.json` via **Preferences: Open Default Settings (JSON)**.
-Click to view Default settings +Click here to view Default settings ```json { From 464e7e2c65c400140f904878974a4a113f42c50d Mon Sep 17 00:00:00 2001 From: gregvanl Date: Mon, 14 Mar 2022 15:22:12 -0700 Subject: [PATCH 34/46] Tune expand default settings message --- docs/getstarted/settings.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md index 1e7db35216..7caae5f039 100644 --- a/docs/getstarted/settings.md +++ b/docs/getstarted/settings.md @@ -16,7 +16,7 @@ VS Code provides two different scopes for settings: * **User Settings** - Settings that apply globally to any instance of VS Code you open. * **Workspace Settings** - Settings stored inside your workspace and only apply when the workspace is opened. -In this article, we'll first describe user settings as these are your personal settings for customizing VS Code. Later we'll cover [Workspace Settings](#workspace-settings), which will be specific to the project you're working on. +In this article, we'll first describe user settings as these are your personal settings for customizing VS Code. Later we'll cover [Workspace settings](#workspace-settings), which will be specific to the project you're working on. ## Settings editor @@ -65,9 +65,9 @@ As an example, let's hide the Activity Bar from VS Code. The Activity Bar is the ![Activity Bar display on the left of the editor](images/settings/activity-bar.png) -Open the Settings Editor (`kb((workbench.action.openSettings)`) and type 'activity' in the Search bar. You should see 5 settings. +Open the Settings Editor (`kb((workbench.action.openSettings)`) and type 'activity' in the Search bar. You should see five settings. -![Settings editor with 'activity' in the Search bar with 5 settings](images/settings/search-for-activity.png) +![Settings editor with 'activity' in the Search bar with five settings](images/settings/search-for-activity.png) You can further limit the scope to just those settings under the **Appearance** group in the left side tree. There should not be just three settings. @@ -96,7 +96,7 @@ There are several other handy filters for searching settings. Here are some of the filters available: * `@ext` - Settings specific to an extension. You provide the extension ID such as `@ext:ms-python.python`. -* `@feature` - Settings specific to a **Features** sub-group. For example, `@feature:explorer` shows settings of the File Explorer. +* `@feature` - Settings specific to a **Features** subgroup. For example, `@feature:explorer` shows settings of the File Explorer. * `@id` - Find a setting based on the setting ID. For example, `@id:workbench.activityBar.visible`. * `@tag` - Settings specific to a system of VS Code. For example, `@tag:workspaceTrust` for settings related to [Workspace Trust](/docs/editor/workspace-trust.md) @@ -162,7 +162,7 @@ Depending on your platform, the user settings file is located here: While you can reset settings individually via the Settings editor **Reset Setting** command, you can reset all changed settings by opening `settings.json` and deleting the entries between the braces `{}`. Be careful since there will be no way to recover your previous setting values. -## Workspace Settings +## Workspace settings Workspace settings are specific to a project and can be shared across developers on a project. Workspace settings override user settings. @@ -313,18 +313,17 @@ If you're using a workspace that needs custom settings but you don't want to app ### Where can I find extension settings? -In general, VS Code extensions store their settings in your user or workspaces settings files and they are available through the Settings editor UI (**Preferences: Open Settings (UI)** - `kb(workbench.action.openSettings)`) or directly in the `settings.json` file (**Preferences: Open Settings (JSON)**). Searching by the extension name (for example `gitlens` or `python`) can help filter down settings to just those contributed by an extension. +In general, VS Code extensions store their settings in your user or workspaces settings files and they are available through the Settings editor UI (**Preferences: Open Settings (UI)**) or via IntelliSense in your `settings.json` file (**Preferences: Open Settings (JSON)**). Searching by the extension name (for example `gitlens` or `python`) can help filter down settings to just those contributed by an extension. ## Default settings Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor or see a read-only version of the `defaultSettings.json` via **Preferences: Open Default Settings (JSON)**.
-Click here to view Default settings +Click here to expand Default settings ```json { - // Editor // Controls whether the editor shows CodeLens. @@ -4193,4 +4192,5 @@ Below are the Visual Studio Code default settings and their values. You can also "npm.scriptExplorerExclude": [] } ``` +
From 970155f480f7f3e8f1815d7afcc9d97a611eeff1 Mon Sep 17 00:00:00 2001 From: Tom Anderson Date: Tue, 15 Mar 2022 10:44:23 +1030 Subject: [PATCH 35/46] Update mac.md The main download link is for an .app file, but the instructions assumed it's a .zip file. No need to extract an .app file. --- docs/setup/mac.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/setup/mac.md b/docs/setup/mac.md index 6811680976..26a7b4c119 100644 --- a/docs/setup/mac.md +++ b/docs/setup/mac.md @@ -12,8 +12,8 @@ MetaDescription: Get Visual Studio Code up and running on Mac (macOS). ## Installation 1. [Download Visual Studio Code](https://go.microsoft.com/fwlink/?LinkID=534106) for macOS. -2. Open the browser's download list and locate the downloaded archive. -3. Extract the archive contents. Use double-click for some browsers or select the 'magnifying glass' icon with Safari. +2. Open the browser's download list and locate the downloaded app or archive. +3. If archive, extract the archive contents. Use double-click for some browsers or select the 'magnifying glass' icon with Safari. 4. Drag `Visual Studio Code.app` to the **Applications** folder, making it available in the macOS Launchpad. 5. Open VS Code from the **Applications** folder, by double clicking the icon. 6. Add VS Code to your Dock by right-clicking on the icon, located in the Dock, to bring up the context menu and choosing **Options**, **Keep in Dock**. From bfde8c5345b6a3918312f7743070bd033621eff5 Mon Sep 17 00:00:00 2001 From: Raju Gupta Date: Tue, 15 Mar 2022 16:25:37 +0100 Subject: [PATCH 36/46] Update ssh.md Fixed grammar. --- docs/containers/ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/containers/ssh.md b/docs/containers/ssh.md index 2b72ab3f4b..1b785228ab 100644 --- a/docs/containers/ssh.md +++ b/docs/containers/ssh.md @@ -9,7 +9,7 @@ MetaDescription: Connect via SSH to Docker engine running on a remote machine an We recommend using the Visual Studio Code [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension to connect to a remote machine running Docker engine. You can use the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions together. You may review the steps in the [remote development documentation](/docs/remote/containers.md#open-a-folder-on-a-remote-ssh-host-in-a-container). -It also possible to connect to the remote Docker engine directly using SSH tunneling, which you can read more about below. +It is also possible to connect to the remote Docker engine directly using SSH tunneling, which you can read more about below. ## Set up SSH Tunneling From 1836e671020fe0ce3c302cf8ccb0a22e07bab50b Mon Sep 17 00:00:00 2001 From: gregvanl Date: Wed, 16 Mar 2022 07:44:55 -0700 Subject: [PATCH 37/46] Remove implied support for end of life Windows 7 --- docs/setup/windows.md | 4 +--- docs/supporting/requirements.md | 6 +----- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/setup/windows.md b/docs/setup/windows.md index b82387e26d..88ffe81ebc 100644 --- a/docs/setup/windows.md +++ b/docs/setup/windows.md @@ -17,8 +17,6 @@ MetaDescription: Get Visual Studio Code up and running on Windows Alternatively, you can also download a [Zip archive](/docs/?dv=winzip), extract it and run Code from there. ->**Note:** .NET Framework 4.5.2 or higher is required for VS Code. If you are using Windows 7, make sure you have at least [.NET Framework 4.5.2](https://www.microsoft.com/download/details.aspx?id=42643) installed. You can check your version of .NET Framework using this command, `reg query "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\full" /v version` from a command prompt. - >**Tip:** Setup will add Visual Studio Code to your `%PATH%`, so from the console you can type 'code .' to open VS Code on that folder. You will need to restart your console after the installation for the change to the `%PATH%` environmental variable to take effect. ## User setup versus system setup @@ -89,7 +87,7 @@ Try using the [zip file](/docs/?dv=winzip) instead of the installer. To use thi ### Icons are missing -I installed Visual Studio Code on my Windows 7 or 8 machine. Why are some icons not appearing in the workbench and editor? +I installed Visual Studio Code on my Windows 8 machine. Why are some icons not appearing in the workbench and editor? VS Code uses [SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) icons and we have found instances where the .SVG file extension is associated with something other than `image/svg+xml`. We're considering options to fix it, but for now here's a workaround: diff --git a/docs/supporting/requirements.md b/docs/supporting/requirements.md index 883cb785ef..23ec4ba3f6 100644 --- a/docs/supporting/requirements.md +++ b/docs/supporting/requirements.md @@ -22,14 +22,10 @@ We recommend: VS Code has been tested on the following platforms: * OS X El Capitan (10.11+) -* Windows 7 (with .NET Framework 4.5.2), 8.0, 8.1 and 10, 11 (32-bit and 64-bit) +* Windows 8.0, 8.1 and 10, 11 (32-bit and 64-bit) * Linux (Debian): Ubuntu Desktop 16.04, Debian 9 * Linux (Red Hat): Red Hat Enterprise Linux 7, CentOS 8, Fedora 24 -### Additional Windows requirements - -Microsoft .NET Framework 4.5.2 is required for VS Code. If you are using Windows 7, please make sure [.NET Framework 4.5.2](https://www.microsoft.com/download/details.aspx?id=42643) is installed. - ### Additional Linux requirements * GLIBCXX version 3.4.21 or later From 0324b2062403c2c4c2a3e33f70ab7e011a6e3597 Mon Sep 17 00:00:00 2001 From: Alex Ross Date: Wed, 16 Mar 2022 16:33:15 +0100 Subject: [PATCH 38/46] Try to improve ${cwd} docs --- docs/editor/variables-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/editor/variables-reference.md b/docs/editor/variables-reference.md index d117b1fb4d..4899efa480 100644 --- a/docs/editor/variables-reference.md +++ b/docs/editor/variables-reference.md @@ -25,7 +25,7 @@ The following predefined variables are supported: - **${fileBasenameNoExtension}** - the current opened file's basename with no file extension - **${fileDirname}** - the current opened file's dirname - **${fileExtname}** - the current opened file's extension -- **${cwd}** - the task runner's current working directory on startup +- **${cwd}** - the task runner's current working directory upon the startup of VS Code - **${lineNumber}** - the current selected line number in the active file - **${selectedText}** - the current selected text in the active file - **${execPath}** - the path to the running VS Code executable From ab434f303cbc2cab627a38fa0981e707e4a3f4cb Mon Sep 17 00:00:00 2001 From: sguitardude Date: Thu, 17 Mar 2022 07:21:57 -0500 Subject: [PATCH 39/46] Property was listed twice. Removed one instance. --- docs/languages/typescript.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/languages/typescript.md b/docs/languages/typescript.md index b15eebce40..e476be908f 100644 --- a/docs/languages/typescript.md +++ b/docs/languages/typescript.md @@ -45,7 +45,7 @@ If semantic highlighting is enabled and the color theme has a corresponding styl Semantic highlighting can change colors based on: -* The resolved type of a symbol: namespace, variable, property, variable, property, class, interface, typeParameter. +* The resolved type of a symbol: namespace, variable, property, variable, class, interface, typeParameter. * Whether the variable/property is read-only (const) or modifiable. * Whether the variable/property type is callable (a function type) or not. From af3a2e8c702cf3260efbab5fdf5b9370bfcbd482 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 17 Mar 2022 14:41:14 -0700 Subject: [PATCH 40/46] Add Uninstall topic --- build/sitemap.xml | 5 +++ docs/setup/setup-overview.md | 2 +- docs/setup/uninstall.md | 71 ++++++++++++++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 docs/setup/uninstall.md diff --git a/build/sitemap.xml b/build/sitemap.xml index 78e76a11cc..e9def56359 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -160,6 +160,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/setup/uninstall + weekly + 0.8 + https://code.visualstudio.com/docs/getstarted/introvideos weekly diff --git a/docs/setup/setup-overview.md b/docs/setup/setup-overview.md index 8a1ff364af..dbc97d10e7 100644 --- a/docs/setup/setup-overview.md +++ b/docs/setup/setup-overview.md @@ -90,7 +90,7 @@ VS Code has detected that some installation files have been modified, perhaps by ### How can I do a 'clean' uninstall of VS Code? -If you want to remove all user data after uninstalling VS Code, you can delete the user data folders `Code` and `.vscode`. This will return you to the state before you installed VS Code. This can also be used to reset all settings if you don't want to uninstall VS Code. +If you want to remove all user data after [uninstalling](/docs/setup/uninstall.md) VS Code, you can delete the user data folders `Code` and `.vscode`. This will return you to the state before you installed VS Code. This can also be used to reset all settings if you don't want to uninstall VS Code. The folder locations will vary depending on your platform: diff --git a/docs/setup/uninstall.md b/docs/setup/uninstall.md new file mode 100644 index 0000000000..4fe52467c6 --- /dev/null +++ b/docs/setup/uninstall.md @@ -0,0 +1,71 @@ +--- +Order: 8 +Area: setup +TOCTitle: Uninstall +ContentId: 435486d3-ad55-4a31-a087-d108f75ba669 +PageTitle: Uninstall Visual Studio Code +DateApproved: 3/3/2022 +MetaDescription: Uninstall Visual Studio Code and clean up. +--- +# Uninstall Visual Studio Code + +The steps for uninstalling Visual Studio Code will depend on your platform (Windows, macOS, or Linux) and the install option that you used. For example on Windows, you can use the System or User Windows Installers or download a `.zip` file and extract the contents anywhere on your machine. + +In general, you would uninstall VS Code as you would any other desktop application and follow your platform's recommended flow for uninstalling software. Specific platform guidance is provided below as well as how to [completely clean up](#clean-uninstall) any remaining VS Code configuration files. + +## Windows + +### Windows Installer + +If you installed VS Code via the Windows Installer, either the User or System version, use the installer to remove VS Code. + +* Start menu + * Search for **Add or Remove Programs** and find Visual Studio Code in the **Apps** > **Apps & features** list. + * Select **Uninstall** from the actions dropdown on the right side (three vertical dots). + * Follow the prompts to uninstall VS Code. +* Control Panel + * Under **Programs**, select the **Uninstall a program** link. + * Find the Visual Studio Code entry, right-click, and select the **Uninstall** command. + * Follow the prompts to uninstall VS Code. + +### .zip file installation + +If you installed VS Code on Windows by downloading and extracting one of the `.zip` files, you can uninstall by deleting the folder where you extracted the `.zip` contents. + +## macOS + +To uninstall VS Code on macOS, open **Finder** and go to **Applications**. Right-click on the Visual Studio Code application and select **Move to Trash**. + +## Linux + +To uninstall VS Code on Linux, you should use your package manager's uninstall or remove option. The exact command line will differ depending on which package manager you used (for example, `apt-get`, `rpn`, `dnf`, `yum`, etc.). + +The names for the VS Code packages are: + +* `code` - VS Code Stable release +* `code-insiders` - VS Code [Insiders](/insiders) release + +For example, if you installed VS Code via the Debian package (`.deb`) and `apt-get` package manager, you would run: + +```bash +sudo apt-get remove code +``` + +where `code` is the name of the VS Code Debian package. + +## Clean uninstall + +If you want to remove all user data after uninstalling VS Code, you can delete the user data folders `Code` and `.vscode`. This will return you to the state before you installed VS Code. This can also be used to reset all settings if you don't want to uninstall VS Code. + +The folder locations will vary depending on your platform: + +* **Windows** - Delete `%APPDATA%\Code` and `%USERPROFILE%\.vscode`. +* **macOS** - Delete `$HOME/Library/Application Support/Code` and `~/.vscode`. +* **Linux** - Delete `$HOME/.config/Code` and `~/.vscode`. + +## Next steps + +* [Setup overview](/docs/setup/overview.md) - General information about VS Code setup and updates. +* [Windows setup](/docs/setup/windows.md) - Details and common questions about installing VS Code on Windows. +* [macOS setup](/docs/setup/mac.md) - VS Code is available for both Intel and Apple Silicon macOS machines. +* [Linux setup](/docs/setup/linux.md) - Learn about the different VS Code packages available for Linux. From ae79d17279962904c5cd891c5e70d5956aa24c53 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Thu, 17 Mar 2022 21:33:07 -0700 Subject: [PATCH 41/46] Fix topic link --- docs/setup/uninstall.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/uninstall.md b/docs/setup/uninstall.md index 4fe52467c6..2de88ea2e8 100644 --- a/docs/setup/uninstall.md +++ b/docs/setup/uninstall.md @@ -65,7 +65,7 @@ The folder locations will vary depending on your platform: ## Next steps -* [Setup overview](/docs/setup/overview.md) - General information about VS Code setup and updates. +* [Setup overview](/docs/setup/setup-overview.md) - General information about VS Code setup and updates. * [Windows setup](/docs/setup/windows.md) - Details and common questions about installing VS Code on Windows. * [macOS setup](/docs/setup/mac.md) - VS Code is available for both Intel and Apple Silicon macOS machines. * [Linux setup](/docs/setup/linux.md) - Learn about the different VS Code packages available for Linux. From 5846e67c33605c988bc3d058a02d346a80b2aee0 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Fri, 18 Mar 2022 18:01:34 +0000 Subject: [PATCH 42/46] Added message about waitFor and Codespaces --- docs/remote/devcontainerjson-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/remote/devcontainerjson-reference.md b/docs/remote/devcontainerjson-reference.md index 79df7e4542..bcee477458 100644 --- a/docs/remote/devcontainerjson-reference.md +++ b/docs/remote/devcontainerjson-reference.md @@ -84,7 +84,7 @@ When creating or working with a dev container, you may need different commands t | `postCreateCommand` | string,
array | This command is the last of three that finalizes container setup when a dev container is created. It happens after `updateContentCommand` and once the dev container has been assigned to a user for the first time.

In GitHub Codespaces, this command can always take advantage of user specific secrets and permissions.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | | `postStartCommand` | string,
array | A command to run each time the container is successfully started.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | | `postAttachCommand` | string,
array | A command to run each time a tool has successfully attached to the container.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | -| `waitFor` | enum | An enum that specifies the command any tool should wait for before connecting. Defaults to `updateContentCommand`. This allows you to use `onCreateCommand` or `updateContentCommand` for steps that must happen before VS Code or other `devcontainer.json` supporting tools connect while still using `postCreateCommand` for steps that can happen behind the scenes afterwards. | +| `waitFor` | enum | An enum that specifies the command any tool should wait for before connecting. Defaults to `updateContentCommand`. This allows you to use `onCreateCommand` or `updateContentCommand` for steps that must happen before VS Code or other `devcontainer.json` supporting tools connect while still using `postCreateCommand` for steps that can happen behind the scenes afterwards.

⚠️ Codespaces does not yet support waitFor.| For each command property, if the value is a single string, it will be run in `/bin/sh`. Use `&&` in a string to execute multiple commands. For example, `"yarn install"` or `"apt-get update && apt-get install -y curl"`. The array syntax `["yarn", "install"]` will invoke the command (in this case `yarn`) directly without using a shell. Each fires after your source code has been mounted, so you can also run shell scripts from your source tree. For example: `bash scripts/install-dev-tools.sh` From c6fb59d27d6f8e9d10c96140c461b2bd7f1b15b0 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Fri, 18 Mar 2022 14:11:23 -0700 Subject: [PATCH 43/46] Format property in recent update --- docs/remote/devcontainerjson-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/remote/devcontainerjson-reference.md b/docs/remote/devcontainerjson-reference.md index bcee477458..15a6bbab2f 100644 --- a/docs/remote/devcontainerjson-reference.md +++ b/docs/remote/devcontainerjson-reference.md @@ -84,7 +84,7 @@ When creating or working with a dev container, you may need different commands t | `postCreateCommand` | string,
array | This command is the last of three that finalizes container setup when a dev container is created. It happens after `updateContentCommand` and once the dev container has been assigned to a user for the first time.

In GitHub Codespaces, this command can always take advantage of user specific secrets and permissions.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | | `postStartCommand` | string,
array | A command to run each time the container is successfully started.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | | `postAttachCommand` | string,
array | A command to run each time a tool has successfully attached to the container.

Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | -| `waitFor` | enum | An enum that specifies the command any tool should wait for before connecting. Defaults to `updateContentCommand`. This allows you to use `onCreateCommand` or `updateContentCommand` for steps that must happen before VS Code or other `devcontainer.json` supporting tools connect while still using `postCreateCommand` for steps that can happen behind the scenes afterwards.

⚠️ Codespaces does not yet support waitFor.| +| `waitFor` | enum | An enum that specifies the command any tool should wait for before connecting. Defaults to `updateContentCommand`. This allows you to use `onCreateCommand` or `updateContentCommand` for steps that must happen before VS Code or other `devcontainer.json` supporting tools connect while still using `postCreateCommand` for steps that can happen behind the scenes afterwards.

⚠️ Codespaces does not yet support `waitFor`.| For each command property, if the value is a single string, it will be run in `/bin/sh`. Use `&&` in a string to execute multiple commands. For example, `"yarn install"` or `"apt-get update && apt-get install -y curl"`. The array syntax `["yarn", "install"]` will invoke the command (in this case `yarn`) directly without using a shell. Each fires after your source code has been mounted, so you can also run shell scripts from your source tree. For example: `bash scripts/install-dev-tools.sh` From e90b6939878660febb36fa3b12d0663211f66b8f Mon Sep 17 00:00:00 2001 From: Radek Simko Date: Mon, 21 Mar 2022 15:02:03 +0000 Subject: [PATCH 44/46] api: document missing semantic highlighting contribution points --- api/references/contribution-points.md | 63 +++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/api/references/contribution-points.md b/api/references/contribution-points.md index 154d3f7417..9e90c70444 100644 --- a/api/references/contribution-points.md +++ b/api/references/contribution-points.md @@ -29,6 +29,9 @@ MetaDescription: To extend Visual Studio Code, your extension (plug-in) declares - [`problemPatterns`](/api/references/contribution-points#contributes.problemPatterns) - [`productIconThemes`](/api/references/contribution-points#contributes.productIconThemes) - [`resourceLabelFormatters`](/api/references/contribution-points#contributes.resourceLabelFormatters) +- [`semanticTokenModifiers`](/api/references/contribution-points#contributes.semanticTokenModifiers) +- [`semanticTokenScopes`](/api/references/contribution-points#contributes.semanticTokenScopes) +- [`semanticTokenTypes`](/api/references/contribution-points#contributes.semanticTokenTypes) - [`snippets`](/api/references/contribution-points#contributes.snippets) - [`submenus`](/api/references/contribution-points#contributes.submenus) - [`taskDefinitions`](/api/references/contribution-points#contributes.taskDefinitions) @@ -1020,6 +1023,66 @@ Contributes resource label formatters that specify how to display URIs everywher This means that all URIs that have a scheme `remotehub` will get rendered by showing only the `path` segment of the URI and the separator will be `/`. Workspaces which have the `remotehub` URI will have the GitHub suffix in their label. +## contributes.semanticTokenModifiers + +Contributes new semantic token modifiers that can be highlighted via theme rules. + +```json +{ + "contributes": { + "semanticTokenModifiers": [ + { + "id": "native", + "description": "Annotates a symbol that is implemented natively" + } + ] + } +} +``` + +See the [Semantic Highlighting Guide](/api/language-extensions/semantic-highlight-guide) to read more about semantic highlighting. + +## contributes.semanticTokenScopes + +Contributes mapping between semantic token types & modifiers and scopes either as a fallback or to support language-specific themes. + +```json +{ + "contributes": { + "semanticTokenScopes": [ + { + "language": "typescript", + "scopes": { + "property.readonly": ["variable.other.constant.property.ts"] + } + } + ] + } +} +``` + +See the [Semantic Highlighting Guide](/api/language-extensions/semantic-highlight-guide) to read more about semantic highlighting. + +## contributes.semanticTokenTypes + +Contributes new semantic token types that can be highlighted via theme rules. + +```json +{ + "contributes": { + "semanticTokenTypes": [ + { + "id": "templateType", + "superType": "type", + "description": "A template type." + } + ] + } +} +``` + +See the [Semantic Highlighting Guide](/api/language-extensions/semantic-highlight-guide) to read more about semantic highlighting. + ## contributes.snippets Contribute snippets for a specific language. The `language` attribute is the [language identifier](/docs/languages/identifiers) and the `path` is the relative path to the snippet file, which defines snippets in the [VS Code snippet format](/docs/editor/userdefinedsnippets#_snippet-syntax). From 77f415a11eddff2c9ae19539a3cb708eeec78cc5 Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 22 Mar 2022 12:31:41 -0700 Subject: [PATCH 45/46] Small edits to recent updates --- api/extension-guides/webview.md | 2 +- api/language-extensions/semantic-highlight-guide.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/api/extension-guides/webview.md b/api/extension-guides/webview.md index 88ed6ffb3d..cd7d6a1fd4 100644 --- a/api/extension-guides/webview.md +++ b/api/extension-guides/webview.md @@ -1032,7 +1032,7 @@ Although `retainContextWhenHidden` may be appealing, keep in mind that this has ## Accessibility -The class `vscode-using-screen-reader` will be added to your webview's main body in contexts where the user is operating vscode with a screen reader. Additionally, the class `vscode-reduce-motion` will be added to the document's main body element in cases where the user has expressed a preference to reduce the amount of motion in the window. By observing these classes and adjusting your rendering accordingly, your webview content can better reflect the user's preferences. +The class `vscode-using-screen-reader` will be added to your webview's main body in contexts where the user is operating VS Code with a screen reader. Additionally, the class `vscode-reduce-motion` will be added to the document's main body element in cases where the user has expressed a preference to reduce the amount of motion in the window. By observing these classes and adjusting your rendering accordingly, your webview content can better reflect the user's preferences. ## Next steps diff --git a/api/language-extensions/semantic-highlight-guide.md b/api/language-extensions/semantic-highlight-guide.md index eaf4863c7e..2e544a8b29 100644 --- a/api/language-extensions/semantic-highlight-guide.md +++ b/api/language-extensions/semantic-highlight-guide.md @@ -150,9 +150,11 @@ If necessary, extensions can declare new types and modifiers or create sub types }] } } +``` In the example above, an extension declares a new type `templateType` and a new modifier `native`. By naming `type` as the super type, styling rules for `type` will also apply to `templateType`: -``` + +```json { "name": "Red Theme", "semanticTokenColors": { @@ -160,10 +162,10 @@ In the example above, an extension declares a new type `templateType` and a new } } ``` -applies to both `type` and all it's subtypes, including `templateType` +The `semanticTokenColors` value shown above applies to both `type` and all it's subtypes, including `templateType`. -Along with custom token types, extensions can define how these are mapped to TextMate scopes. This is described in the [Custom Mappings](#custom-textmate-scope-mappings) section. Note that custom mapping rules are not automatically inherited from the super type. Instead, subtypes need to refefine the mapping, preferrably to more specific scopes. +Along with custom token types, extensions can define how these are mapped to TextMate scopes. This is described in the [Custom Mappings](#custom-textmate-scope-mappings) section. Note that custom mapping rules are not automatically inherited from the super type. Instead, subtypes need to redefine the mapping, preferably to more specific scopes. ## Enablement of semantic highlighting From 475e4cc4323ad5a4449cd5e57058513eb04e480a Mon Sep 17 00:00:00 2001 From: gregvanl Date: Tue, 22 Mar 2022 13:29:20 -0700 Subject: [PATCH 46/46] Remove collapsable Default Settings section --- docs/getstarted/settings.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/getstarted/settings.md b/docs/getstarted/settings.md index 7caae5f039..7a855572f2 100644 --- a/docs/getstarted/settings.md +++ b/docs/getstarted/settings.md @@ -319,9 +319,6 @@ In general, VS Code extensions store their settings in your user or workspaces s Below are the Visual Studio Code default settings and their values. You can also view the default values in the Settings editor or see a read-only version of the `defaultSettings.json` via **Preferences: Open Default Settings (JSON)**. -
-Click here to expand Default settings - ```json { // Editor @@ -4192,5 +4189,3 @@ Below are the Visual Studio Code default settings and their values. You can also "npm.scriptExplorerExclude": [] } ``` - -