From 5614258cc7673a1428c7f4fe6ef2d030cf71862c Mon Sep 17 00:00:00 2001
From: JiaLiPassion <JiaLi.Passion@gmail.com>
Date: Sat, 12 Sep 2020 10:41:09 +0900
Subject: [PATCH] docs(zone.js): Add breaking changes info for zone.js v0.11.1
 (#38821)

Before Zone.js `v0.11.1`, Zone.js provides two format of bundles under `dist` folder,
`ES5` bundle `zone.js` and `ES2015` bundle `zone-evergreen.js`, these bundles are used
for `differential loading` of Angular. By default, the following code

```
import 'zone.js';
```

loads the `ES5` bundle `zone.js`.

From `v0.11.1`, Zone.js follows the [Angular Package Format]
(https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs),
so the folder structure of the Zone.js bundles is updated to match `Angular Package Format`.

So the same code

```
import 'zone.js';
```
loads the `ES2015` bundle.

This is a breaking change, so if the apps import zone.js in this way,
the apps will not work in legacy browsers such as `IE11`.

Zone.js still provides the same bundles under `dist` folder to keep backward
compatibility after `v0.11.1`. So the following code in `polyfills.ts` generated
by `Angular CLI` still works.

```
import 'zone.js/dist/zone';
```

For details, please refer the [changelog](./CHANGELOG.md) and
the [PR](https://github.com/angular/angular/pull/36540).

PR Close #38821
---
 packages/zone.js/CHANGELOG.md | 29 +++++++++++++++++++++++++++++
 packages/zone.js/README.md    | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/packages/zone.js/CHANGELOG.md b/packages/zone.js/CHANGELOG.md
index a8b2612d1e..c6e99949cd 100644
--- a/packages/zone.js/CHANGELOG.md
+++ b/packages/zone.js/CHANGELOG.md
@@ -7,6 +7,35 @@
 * **zone.js:** zone.js package.json should not include files/directories field ([#38528](https://github.com/angular/angular/issues/38528)) ([6b662d1](https://github.com/angular/angular/commit/6b662d1)), closes [#38526](https://github.com/angular/angular/issues/38526) [#38516](https://github.com/angular/angular/issues/38516) [#38513](https://github.com/angular/angular/issues/38513)
 
 
+# BREAKING CHANGES since Zone.js v0.11.1
+
+Prior to `v0.11.1`, Zone.js provided two distribution bundle formats in the `dist` folder.
+They were (1) `ES5` bundle distributed as `zone.js` and (2) `ES2015` bundle distributed as `zone-evergreen.js`.
+These bundles are used for Angular's differential-loading mechanism. 
+
+Prior to `v0.11.11` the following code
+
+```
+import 'zone.js';
+```
+would load the `ES5` bundle from `dist/zone.js`.
+
+Starting with `v0.11.1`, Zone.js follows the [Angular Package Format](https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs), so the folder structure of the Zone.js bundles is updated to match `Angular Package Format`.
+So the same code
+
+```
+import 'zone.js';
+```
+now loads the `ES2015` bundle instead.
+
+This is a breaking change for legacy browsers such as `IE11`.
+
+For backwards compatibility `zone.js` continues to distribute the same bundles under `dist`.
+To restore the old behavior change the `polyfills.ts` generated by `Angular CLI` to import like so:
+
+```
+import 'zone.js/dist/zone';
+```
 
 <a name="0.11.0"></a>
 # [0.11.0](https://github.com/angular/angular/compare/zone.js-0.10.3...zone.js-0.11.0) (2020-08-14)
diff --git a/packages/zone.js/README.md b/packages/zone.js/README.md
index d356f4eabc..ed95778d06 100644
--- a/packages/zone.js/README.md
+++ b/packages/zone.js/README.md
@@ -17,6 +17,38 @@ See the new API [here](./lib/zone.ts).
 
 Read up on [Zone Primer](https://docs.google.com/document/d/1F5Ug0jcrm031vhSMJEOgp1l-Is-Vf0UCNDY-LsQtAIY).
 
+# BREAKING CHANGES since Zone.js v0.11.1
+
+Prior to `v0.11.1`, Zone.js provided two distribution bundle formats in the `dist` folder.
+They were (1) `ES5` bundle distributed as `zone.js` and (2) `ES2015` bundle distributed as `zone-evergreen.js`.
+These bundles are used for Angular's differential-loading mechanism. 
+
+Prior to `v0.11.11` the following code
+
+```
+import 'zone.js';
+```
+would load the `ES5` bundle from `dist/zone.js`.
+
+Starting with `v0.11.1`, Zone.js follows the [Angular Package Format](https://docs.google.com/document/d/1CZC2rcpxffTDfRDs6p1cfbmKNLA6x5O-NtkJglDaBVs), so the folder structure of the Zone.js bundles is updated to match `Angular Package Format`.
+So the same code
+
+```
+import 'zone.js';
+```
+now loads the `ES2015` bundle instead.
+
+This is a breaking change for legacy browsers such as `IE11`.
+
+For backwards compatibility `zone.js` continues to distribute the same bundles under `dist`.
+To restore the old behavior change the `polyfills.ts` generated by `Angular CLI` to import like so:
+
+```
+import 'zone.js/dist/zone';
+```
+
+For details, please refer the [changelog](./CHANGELOG.md) and the [PR](https://github.com/angular/angular/pull/36540).
+
 ## What's a Zone?
 
 A Zone is an execution context that persists across async tasks.