From bc102559e553a09f5105467f15b260b1596bb28e Mon Sep 17 00:00:00 2001
From: Ed Pelc <ed@freightchick.com>
Date: Thu, 13 Apr 2017 13:54:57 -0400
Subject: [PATCH] docs(guides): add guide for using compatibility mode

Fixes #4018
---
 guides/compatibility-mode.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 guides/compatibility-mode.md

diff --git a/guides/compatibility-mode.md b/guides/compatibility-mode.md
new file mode 100644
index 000000000000..7ee532cd1285
--- /dev/null
+++ b/guides/compatibility-mode.md
@@ -0,0 +1,32 @@
+# Compatibility Mode
+Compatibility mode allows `@angular/material` to work with [Angular Material for AngularJS](https://material.angularjs.org/latest/).
+
+## Upgrade Process Overview
+Below is a general overview of the upgrade process for an AngularJS application which uses [Angular Material for AngularJS](https://material.angularjs.org/latest/) and wishes to upgrade to Angular 2+ with `@angular/material`.
+1. Setup `@angular/upgrade/static` and bootstrap Angular in your AngularJS project
+2. Setup and enable compatibility mode for `@angular/material`
+3. Convert all components over to Angular and `@angular/material`
+4. Remove Angular Material for AngularJS
+5. Disable compatibility mode
+  - Find/replace `mat-` with `md-`
+  - Remove `NoConflictStyleCompatibilityMode`
+
+
+## Upgrade Checklist
+- [ ] Switch all `@angular/material` component prefixes in templates from `md-` to `mat-`
+  - See [this](https://github.com/angular/material2/blob/master/src/lib/core/compatibility/compatibility.ts#L33-L150) for a list of all components you need to rename.
+    - Do not forget to update attributes such as `mdTooltip` -> `matTooltip`
+  > NOTE you are only renaming `@angular/material` components(for Angular 2+) in your project.
+- [ ] Import `NoConflictStyleCompatibilityMode` to shows errors when you use `md-` instead of `mat-`(compatibility) for your prefix.
+
+
+
+## FAQ
+View the [compatibility tests](https://github.com/angular/material2/blob/master/src/lib/core/compatibility/compatibility.ts) for some info/examples.
+
+- What is Compatibility Mode?
+  - Compatibility Mode allows you to use `@angular/material` and [Angular Material for AngularJS](https://material.angularjs.org/latest/) in the same project without running into issues(css selector overlap, js issues, etc)
+- What is `mat-`?
+  - This is the prefix used for `@angular/material` when it is running in compatibility mode.
+- How do I find out which element is using `md-` instead of `mat-`?
+  - If you are using 2.0.0-beta-3 or earlier, the error message isn't very helpful. Either wait for a new release or install the latest master to get this [fix](https://github.com/angular/material2/commit/2d500445d4f53055623250dc18569241f7b4fceb).