From 6ee3892db5dea9acd5af27e84918a48e2c5cb74b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= <mbajtoss@gmail.com>
Date: Mon, 14 Oct 2019 16:34:51 +0200
Subject: [PATCH] docs: add a skeleton of migration guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>
---
 .../Migrating-from-LoopBack-3-redirect.md     | 10 +++
 .../migration/authentication-authorization.md | 15 +++++
 docs/site/migration/boot-scripts.md           |  9 +++
 docs/site/migration/clients.md                | 16 +++++
 docs/site/migration/datasources.md            |  9 +++
 docs/site/migration/express-middleware.md     | 10 +++
 docs/site/migration/extensions.md             | 10 +++
 docs/site/migration/models/core.md            | 15 +++++
 docs/site/migration/models/methods.md         | 12 ++++
 docs/site/migration/models/mixins.md          |  9 +++
 docs/site/migration/models/operation-hooks.md |  9 +++
 docs/site/migration/models/overview.md        | 10 +++
 docs/site/migration/models/relations.md       | 13 ++++
 docs/site/migration/models/remoting-hooks.md  | 16 +++++
 .../mounting-lb3app.md}                       |  6 +-
 docs/site/migration/overview.md               | 12 ++++
 docs/site/sidebars/lb4_sidebar.yml            | 61 +++++++++++++++++--
 17 files changed, 235 insertions(+), 7 deletions(-)
 create mode 100644 docs/site/Migrating-from-LoopBack-3-redirect.md
 create mode 100644 docs/site/migration/authentication-authorization.md
 create mode 100644 docs/site/migration/boot-scripts.md
 create mode 100644 docs/site/migration/clients.md
 create mode 100644 docs/site/migration/datasources.md
 create mode 100644 docs/site/migration/express-middleware.md
 create mode 100644 docs/site/migration/extensions.md
 create mode 100644 docs/site/migration/models/core.md
 create mode 100644 docs/site/migration/models/methods.md
 create mode 100644 docs/site/migration/models/mixins.md
 create mode 100644 docs/site/migration/models/operation-hooks.md
 create mode 100644 docs/site/migration/models/overview.md
 create mode 100644 docs/site/migration/models/relations.md
 create mode 100644 docs/site/migration/models/remoting-hooks.md
 rename docs/site/{Migrating-from-LoopBack-3.md => migration/mounting-lb3app.md} (94%)
 create mode 100644 docs/site/migration/overview.md

diff --git a/docs/site/Migrating-from-LoopBack-3-redirect.md b/docs/site/Migrating-from-LoopBack-3-redirect.md
new file mode 100644
index 000000000000..86f1738438f6
--- /dev/null
+++ b/docs/site/Migrating-from-LoopBack-3-redirect.md
@@ -0,0 +1,10 @@
+---
+lang: en
+title: 'Migrating from LoopBack 3'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Migrating-from-LoopBack-3.html
+---
+
+The migration guide was moved to a new place:
+[Migration guide](./migration-overview.md).
diff --git a/docs/site/migration/authentication-authorization.md b/docs/site/migration/authentication-authorization.md
new file mode 100644
index 000000000000..3ebc1ff3de0e
--- /dev/null
+++ b/docs/site/migration/authentication-authorization.md
@@ -0,0 +1,15 @@
+---
+lang: en
+title: 'Migrating authentication and authorization'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-authentication-authorization.html
+---
+
+TODO: explain how to migrate:
+
+- authentication
+- authorization
+- built-in models (User, AccessToken, ACL)
+- loopback-component-oauth2
+- loopback-component-passport
diff --git a/docs/site/migration/boot-scripts.md b/docs/site/migration/boot-scripts.md
new file mode 100644
index 000000000000..9a03f179c6d5
--- /dev/null
+++ b/docs/site/migration/boot-scripts.md
@@ -0,0 +1,9 @@
+---
+lang: en
+title: 'Migrating boot scripts'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-boot-scripts.html
+---
+
+TODO: Explain how to migrate LB3 boot scripts to LB4 LifeCycle observers.
diff --git a/docs/site/migration/clients.md b/docs/site/migration/clients.md
new file mode 100644
index 000000000000..60858f9aac96
--- /dev/null
+++ b/docs/site/migration/clients.md
@@ -0,0 +1,16 @@
+---
+lang: en
+title: 'Migrating clients'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-clients.html
+---
+
+Explain how to migrate client code using one of LB3 client SDKs:
+
+- AngularJS (1.x)
+- Angular (2+) (see loopback-sdk-builder)
+- Android
+- iOS
+- Xamarin
+- Isomorphic JavaScript
diff --git a/docs/site/migration/datasources.md b/docs/site/migration/datasources.md
new file mode 100644
index 000000000000..fc5118221251
--- /dev/null
+++ b/docs/site/migration/datasources.md
@@ -0,0 +1,9 @@
+---
+lang: en
+title: 'Migrating datasources'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-datasources.html
+---
+
+TODO: show how to migrate a datasource from a LB3 app to LB4.
diff --git a/docs/site/migration/express-middleware.md b/docs/site/migration/express-middleware.md
new file mode 100644
index 000000000000..3d6b5df8fabb
--- /dev/null
+++ b/docs/site/migration/express-middleware.md
@@ -0,0 +1,10 @@
+---
+lang: en
+title: 'Migrating Express middleware'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-express-middleware.html
+---
+
+TODO: show how to migrate a Express middleware from a LB3 app mounted inside LB4
+to top-level, so that the middleware is executed for both LB3 and LB4 endpoints.
diff --git a/docs/site/migration/extensions.md b/docs/site/migration/extensions.md
new file mode 100644
index 000000000000..eff7bd3e5b6d
--- /dev/null
+++ b/docs/site/migration/extensions.md
@@ -0,0 +1,10 @@
+---
+lang: en
+title: 'Migrating components and extensions'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-extensions.html
+---
+
+TODO: explain how to migrate custom LB3 components/extensions written by our
+community to make them usable in LB4 projects.
diff --git a/docs/site/migration/models/core.md b/docs/site/migration/models/core.md
new file mode 100644
index 000000000000..d80c8f22d0cb
--- /dev/null
+++ b/docs/site/migration/models/core.md
@@ -0,0 +1,15 @@
+---
+lang: en
+title: 'Migrating models'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-core.html
+---
+
+TODO: Explain how to migrate core Model functionality:
+
+- Model definition
+- Persistence (via LB4 repositories)
+- REST API (via LB4 controllers)
+
+Show how to use `lb4 import-model`.
diff --git a/docs/site/migration/models/methods.md b/docs/site/migration/models/methods.md
new file mode 100644
index 000000000000..e5f56d5c75bc
--- /dev/null
+++ b/docs/site/migration/models/methods.md
@@ -0,0 +1,12 @@
+---
+lang: en
+title: 'Migrating custom model methods'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-methods.html
+---
+
+TODO: Explain how to migrate custom model methods:
+
+- Methods related to persistence go to LB4 Repository
+- Remote methods (public API) go to Controller class
diff --git a/docs/site/migration/models/mixins.md b/docs/site/migration/models/mixins.md
new file mode 100644
index 000000000000..d18f9ffeb254
--- /dev/null
+++ b/docs/site/migration/models/mixins.md
@@ -0,0 +1,9 @@
+---
+lang: en
+title: 'Migrating model mixins'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-mixins.html
+---
+
+TODO: Explain how to migrate model mixins.
diff --git a/docs/site/migration/models/operation-hooks.md b/docs/site/migration/models/operation-hooks.md
new file mode 100644
index 000000000000..6325176593f5
--- /dev/null
+++ b/docs/site/migration/models/operation-hooks.md
@@ -0,0 +1,9 @@
+---
+lang: en
+title: 'Migrating CRUD operation hooks'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-operation-hooks.html
+---
+
+TODO: Explain how to migrate CRUD Operation Hooks.
diff --git a/docs/site/migration/models/overview.md b/docs/site/migration/models/overview.md
new file mode 100644
index 000000000000..d6bb2a605a93
--- /dev/null
+++ b/docs/site/migration/models/overview.md
@@ -0,0 +1,10 @@
+---
+lang: en
+title: 'Migrating models'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-overview.html
+---
+
+TODO: Explain at high level how to migrate models from a LB3 app to a LB4
+project. Refer to sub-sections for model details.
diff --git a/docs/site/migration/models/relations.md b/docs/site/migration/models/relations.md
new file mode 100644
index 000000000000..8bf23c2c8026
--- /dev/null
+++ b/docs/site/migration/models/relations.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating model relations'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-relations.html
+---
+
+TODO: Explain how to migrate model relations:
+
+- Relation definition to LB4 model class
+- Persistence (via LB4 Repositories), including inclusion resolver
+- REST API (via LB4 Controllers)
diff --git a/docs/site/migration/models/remoting-hooks.md b/docs/site/migration/models/remoting-hooks.md
new file mode 100644
index 000000000000..dc803d2d9fd8
--- /dev/null
+++ b/docs/site/migration/models/remoting-hooks.md
@@ -0,0 +1,16 @@
+---
+lang: en
+title: 'Migrating remoting hooks'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-remoting-hooks.html
+---
+
+TODO: Explain how to migrate remoting hooks to LB4 interceptors.
+
+- Global hooks, e.g. `app.beforeRemote('**', handlerFn)`
+- Model-level hooks, e.g. `app.beforeRemote('User.**', handlerFn)`
+- Method-level hooks, e.g. `User.beforeRemote('create', handlerFn)`
+
+Explain how to map properties provided by LB3 remoting context to LB4 concepts
+and how to access those data via Dependency Injection.
diff --git a/docs/site/Migrating-from-LoopBack-3.md b/docs/site/migration/mounting-lb3app.md
similarity index 94%
rename from docs/site/Migrating-from-LoopBack-3.md
rename to docs/site/migration/mounting-lb3app.md
index 7f27c9457560..4366647a55a9 100644
--- a/docs/site/Migrating-from-LoopBack-3.md
+++ b/docs/site/migration/mounting-lb3app.md
@@ -1,9 +1,9 @@
 ---
 lang: en
-title: 'Migrating from LoopBack 3'
-keywords: LoopBack 4.0, LoopBack 4, LoopBack 3
+title: 'Mounting a LoopBack 3 application'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
 sidebar: lb4_sidebar
-permalink: /doc/en/lb4/Migrating-from-LoopBack-3.html
+permalink: /doc/en/lb4/migration-mounting-lb3app.html
 ---
 
 For current LoopBack 3 users who want to migrate to LoopBack 4, LoopBack 4
diff --git a/docs/site/migration/overview.md b/docs/site/migration/overview.md
new file mode 100644
index 000000000000..0e702d0a9e33
--- /dev/null
+++ b/docs/site/migration/overview.md
@@ -0,0 +1,12 @@
+---
+lang: en
+title: 'Migration guide'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-overview.html
+---
+
+Migration guide from LoopBack 3 to LoopBack 4.
+
+TODO: explain the high-level plan for upgrading in incremental steps, point to
+sub-chapters for more details.
diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
index f9d672fda331..7a5b7b57a658 100644
--- a/docs/site/sidebars/lb4_sidebar.yml
+++ b/docs/site/sidebars/lb4_sidebar.yml
@@ -620,8 +620,8 @@ children:
   url: apidocs.index.html
   output: 'web, pdf'
 
-- title: 'For LoopBack 3.x users'
-  url: LoopBack-3.x.html
+- title: 'Migration guide'
+  url: 'migration-overview.html'
   output: 'web, pdf'
   children:
 
@@ -629,8 +629,61 @@ children:
     url: Understanding-the-differences.html
     output: 'web, pdf'
 
-  - title: 'Migrating from LoopBack 3'
-    url: Migrating-from-LoopBack-3.html
+  - title: 'Mounting a LoopBack 3 application'
+    url: migration-mounting-lb3app.html
+    output: 'web, pdf'
+
+  - title: 'Migrating datasources'
+    url: migration-datasources.html
+    output: 'web, pdf'
+
+  - title: 'Migrating Express middleware'
+    url: migration-express-middleware.html
+    output: 'web, pdf'
+
+  - title: 'Migrating models'
+    url: migration-models-overview.html
+    output: 'web, pdf'
+    children:
+
+    - title: 'Model definitions and built-in APIs'
+      url: migration-models-core.html
+      output: 'web, pdf'
+
+    - title: 'Relations'
+      url: migration-models-relations.html
+      output: 'web, pdf'
+
+    - title: 'Custom methods'
+      url: migration-models-methods.html
+      output: 'web, pdf'
+
+    - title: 'Remoting hooks'
+      url: migration-models-remoting-hooks.html
+      output: 'web, pdf'
+
+    - title: 'CRUD operation hooks'
+      url: migration-models-operation-hooks.html
+      output: 'web, pdf'
+
+    - title: 'Mixins'
+      url: migration-models-mixins.html
+      output: 'web, pdf'
+
+  - title: 'Boot scripts'
+    url: migration-boot-scripts.html
+    output: 'web, pdf'
+
+  - title: 'Authentication & authorization'
+    url: migration-authentication-authorization.html
+    output: 'web, pdf'
+
+  - title: 'Components and extensions'
+    url: migration-extensions.html
+    output: 'web, pdf'
+
+  - title: 'Clients (API consumers)'
+    url: migration-clients.html
     output: 'web, pdf'
 
 - title: 'Best practices'