From 9d88ca07f8283b30dc56ecf8cd31db299d500a36 Mon Sep 17 00:00:00 2001
From: Charles Lyding <19598772+clydin@users.noreply.github.com>
Date: Mon, 8 Jun 2020 21:41:50 -0400
Subject: [PATCH] docs: add solution-style tsconfig migration docs (#37512)

This adds documentation for the v10.0 tooling migration `solution-style-tsconfig` contained within the `@schematics/angular` package.

PR Close #37512
---
 .pullapprove.yml                              |  1 +
 .../migration-solution-style-tsconfig.md      | 54 +++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 aio/content/guide/migration-solution-style-tsconfig.md

diff --git a/.pullapprove.yml b/.pullapprove.yml
index 21b4b27b64..0b94eb943b 100644
--- a/.pullapprove.yml
+++ b/.pullapprove.yml
@@ -961,6 +961,7 @@ groups:
           'aio/content/guide/strict-mode.md',
           'aio/content/guide/web-worker.md',
           'aio/content/guide/workspace-config.md',
+          'aio/content/guide/migration-solution-style-tsconfig.md',
           ])
     reviewers:
       users:
diff --git a/aio/content/guide/migration-solution-style-tsconfig.md b/aio/content/guide/migration-solution-style-tsconfig.md
new file mode 100644
index 0000000000..6cc7cc94f4
--- /dev/null
+++ b/aio/content/guide/migration-solution-style-tsconfig.md
@@ -0,0 +1,54 @@
+# Solution-style `tsconfig.json` migration
+
+## What does this migration do?
+
+This migration adds support to existing projects for TypeScript's new ["solution-style" tsconfig feature](https://devblogs.microsoft.com/typescript/announcing-typescript-3-9/#solution-style-tsconfig).
+
+Support is added by making two changes:
+1. Renaming the workspace-level `tsconfig.json` to `tsconfig.base.json`.
+All project [TypeScript configuration files](guide/typescript-configuration) will extend from this base which contains the common options used throughout the workspace.
+
+2. Adding the solution `tsconfig.json` file at the root of the workspace.
+This `tsconfig.json` file will only contain references to project-level TypeScript configuration files and is only used by editors/IDEs.
+
+As an example, the solution `tsconfig.json` for a new project is as follows:
+```json
+// This is a "Solution Style" tsconfig.json file, and is used by editors and TypeScript’s language server to improve development experience.
+// It is not intended to be used to perform a compilation.
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    },
+    {
+      "path": "./e2e/tsconfig.json"
+    }
+  ]
+}
+```
+
+## Why is this migration necessary?
+
+Solution-style `tsconfig.json` files provide an improved editing experience and fix several long-standing defects when editing files in an IDE.
+IDEs that leverage the TypeScript language service (for example, [Visual Studio Code](https://code.visualstudio.com)), will only use TypeScript configuration files that are named `tsconfig.json`.
+In complex projects, there may be more than one compilation unit and each of these units may have different settings and options.
+
+With the Angular CLI, a project will have application code that will target a browser.
+It will also have unit tests that should not be included within the built application and that also need additional type information present (`jasmine` in this case).
+Both parts of the project also share some but not all of the code within the project.
+As a result, two separate TypeScript configuration files (`tsconfig.app.json` and `tsconfig.spec.json`) are needed to ensure that each part of the application is configured properly and that the right types are used for each part.
+Also if web workers are used within a project, an additional tsconfig (`tsconfig.worker.json`) is needed.
+Web workers use similar but incompatible types to the main browser application.
+This requires the additional configuration file to ensure that the web worker files use the appropriate types and will build successfully.
+
+While the Angular build system knows about all of these TypeScript configuration files, an IDE using TypeScript's language service does not.
+Because of this, an IDE will not be able to properly analyze the code from each part of the project and may generate false errors or make suggestions that are incorrect for certain files.
+By leveraging the new solution-style tsconfig, the IDE can now be aware of the configuration of each part of a project.
+This allows each file to be treated appropriately based on its tsconfig.
+IDE features such as error/warning reporting and auto-suggestion will operate more effectively as well.
+
+The TypeScript 3.9 release [blog post](https://devblogs.microsoft.com/typescript/announcing-typescript-3-9/#solution-style-tsconfig) also contains some additional information regarding this new feature.