From 71c0363bb576ef909d81882f8ec9c69392e05bd0 Mon Sep 17 00:00:00 2001
From: Charles Lyding <19598772+clydin@users.noreply.github.com>
Date: Tue, 2 Jun 2020 14:37:27 -0400
Subject: [PATCH] docs: add tslib update migration docs (#37402)

This adds documentation for the v10.0 tooling migration `update-libraries-tslib` contained within the `@schematics/angular` package.

PR Close #37402
---
 .pullapprove.yml                              |  1 +
 .../guide/migration-update-libraries-tslib.md | 52 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 aio/content/guide/migration-update-libraries-tslib.md

diff --git a/.pullapprove.yml b/.pullapprove.yml
index 6a85edb22b..2c0c1f109f 100644
--- a/.pullapprove.yml
+++ b/.pullapprove.yml
@@ -963,6 +963,7 @@ groups:
           'aio/content/guide/workspace-config.md',
           'aio/content/guide/migration-solution-style-tsconfig.md',
           'aio/content/guide/migration-update-module-and-target-compiler-options.md',
+          'aio/content/guide/migration-update-libraries-tslib.md',
           ])
     reviewers:
       users:
diff --git a/aio/content/guide/migration-update-libraries-tslib.md b/aio/content/guide/migration-update-libraries-tslib.md
new file mode 100644
index 0000000000..54fc89ba73
--- /dev/null
+++ b/aio/content/guide/migration-update-libraries-tslib.md
@@ -0,0 +1,52 @@
+# tslib Direct Dependency Migration
+
+## What does this migration do?
+
+If you have any libraries within your workspace, this migration will convert `tslib` peer dependencies to direct dependencies for the libraries.
+TypeScript uses the `tslib` package to provide common helper functions used in compiled TypeScript code.
+The `tslib` version is also updated to `2.0.0` to support TypeScript 3.9.
+
+Before:
+```json
+{
+  "name": "my-lib",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": "^9.0.0",
+    "@angular/core": "^9.0.0",
+    "tslib": "^1.12.0"
+  }
+}
+```
+
+After:
+```json
+{
+  "name": "my-lib",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": "^9.0.0",
+    "@angular/core": "^9.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.0.0"
+  }
+}
+```
+
+## Why is this migration necessary?
+
+The [`tslib`](https://github.com/Microsoft/tslib) is a runtime library for Typescript.
+The version of this library is bound to the version of the TypeScript compiler used to compile a library.
+Peer dependencies do not accurately represent this relationship between the runtime and the compiler.
+If `tslib` remained declared as a library peer dependency, it would be possible for some Angular workspaces to get into a state where the workspace could not satisfy `tslib` peer dependency requirements for multiple libraries, resulting in build-time or run-time errors.
+
+As of TypeScript 3.9 (used by Angular v10), `tslib` version of 2.x is required to build new applications.
+However, older libraries built with previous version of TypeScript and already published to npm might need `tslib` 1.x.
+This migration makes it possible for code depending on incompatible versions of the `tslib` runtime library to remain interoperable.
+
+
+## Do I still need `tslib` as a dependency in my workspace `package.json`?
+
+Yes.
+The `tslib` dependency declared in the `package.json` file of the workspace is used to build applications within this workspace, as well as run unit tests for workspace libraries, and is required.