angular · filipesilva · Mar 28, 2019 · gkalpak · Mar 25, 2019 · filipesilva
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@ pubspec.lock
 .idea/
 .settings/
 .vscode/launch.json
+.vscode/settings.json
 *.swo
 modules/.settings
 modules/.vscode

diff --git a/.vscode/README.md b/.vscode/README.md
@@ -0,0 +1,23 @@
+# VSCode Configuration
+
+This folder contains opt-in [Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) and [Extension Recommendations](https://code.visualstudio.com/docs/editor/extension-gallery#_workspace-recommended-extensions) that the Angular team recommends using when working on this repository.
+
+## Usage
+
+To use the recommended settings follow the steps below:
+
+- install <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>
+- copy `.vscode/recommended-settings.json` to `.vscode/settings.json`
+- restart the editor
+
+If you already have your custom workspace settings you should instead manually merge the file content.
+
+This isn't an automatic process so you will need to repeat it when settings are updated.
+
+To see the recommended extensions select "Extensions: Show Recommended Extensions" in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
+
+## Editing `.vscode/recommended-settings.json`
+
+If you wish to add extra configuration items please keep in mind any settings you add here will be used by many users.
+
+Try to keep these settings to things that help facilitate the development process and avoid altering the user workflow whenever possible.
diff --git a/.vscode/settings.json → .vscode/recommended-settings.json b/.vscode/settings.json → .vscode/recommended-settings.json
@@ -1,4 +1,7 @@
 {
+  // Format js and ts files on save with `clang-format.executable`
+  // If `clang-format.executable` is not being used, these two settings should be removed otherwise it will break existing formatting.
+  // You can instead run `yarn gulp format` to manually format your code.
   "[javascript]": {
     "editor.formatOnSave": true,
   },
@@ -8,6 +11,7 @@
   // Please install https://marketplace.visualstudio.com/items?itemName=xaver.clang-format to take advantage of `clang-format` in VSCode.
   // (See https://clang.llvm.org/docs/ClangFormat.html for more info `clang-format`.)
   "clang-format.executable": "${workspaceRoot}/node_modules/.bin/clang-format",
+  // Exclude third party modules and build artifacts from the editor watchers/searches.
   "files.watcherExclude": {
     "**/.git/objects/**": true,
     "**/.git/subtree-cache/**": true,