docs: add a skeleton of migration guide

bajtos · bajtos · commit 1ef5b1ca732b · 2019-10-18T07:55:50.000+02:00
Signed-off-by: Miroslav Bajtoš &lt;mbajtoss@gmail.com&gt;
diff --git a/docs/site/Migrating-from-LoopBack-3-redirect.md 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/auth/built-in.md b/docs/site/migration/auth/built-in.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating built-in authentication and authorization'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-auth-built-in.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3719](https://github.com/strongloop/loopback-next/issues/3719)
+" %}
diff --git a/docs/site/migration/auth/oauth2.md b/docs/site/migration/auth/oauth2.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating OAuth2 provider'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-auth-oauth2.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3959](https://github.com/strongloop/loopback-next/issues/3959)
+" %}
diff --git a/docs/site/migration/auth/overview.md b/docs/site/migration/auth/overview.md
@@ -0,0 +1,28 @@
+---
+lang: en
+title: 'Migrating authentication and authorization'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-auth-overview.html
+---
+
+LoopBack version 3 provides several options for adding authentication and
+authorization to secure the applications:
+
+- A set of built-in models like `User`, `AccessToken` and `ACL` makes it easy to
+  store your user credentials locally and define custom access control checks.
+  The migration path is described in
+  [Migrating built-in authentication and authorization](./built-in.md).
+
+- [loopback-component-passport](https://github.com/strongloop/loopback-component-passport)
+  provides integration between LoopBack 3 and
+  [Passport](http://www.passportjs.org) to support third-party login and account
+  linking for LoopBack applications. The migration path is described in
+  [Migrating Passport-based authentication](./passport.md).
+
+- [loopback-component-oauth2](https://github.com/strongloop/loopback-component-oauth2)
+  provides full integration between OAuth 2.0 and LoopBack. It enables LoopBack
+  applications to function as an oAuth 2.0 provider to authenticate and
+  authorize client applications and/or resource owners (i.e. users) to access
+  protected API endpoints. The migration path is described in
+  [Migrating OAuth2 provider](./oauth2.md).
diff --git a/docs/site/migration/auth/passport.md b/docs/site/migration/auth/passport.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating Passport-based authentication'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-auth-passport.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3958](https://github.com/strongloop/loopback-next/issues/3958)
+" %}
diff --git a/docs/site/migration/boot-scripts.md b/docs/site/migration/boot-scripts.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3957](https://github.com/strongloop/loopback-next/issues/3957)
+" %}
diff --git a/docs/site/migration/cli.md b/docs/site/migration/cli.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating CLI usage patterns'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-cli.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3953](https://github.com/strongloop/loopback-next/issues/3953)
+" %}
diff --git a/docs/site/migration/clients.md b/docs/site/migration/clients.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating clients'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-clients.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3954](https://github.com/strongloop/loopback-next/issues/3954)
+" %}
diff --git a/docs/site/migration/datasources.md b/docs/site/migration/datasources.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating datasources'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-datasources.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3946](https://github.com/strongloop/loopback-next/issues/3946).
+" %}
diff --git a/docs/site/migration/express-middleware.md b/docs/site/migration/express-middleware.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3947](https://github.com/strongloop/loopback-next/issues/3947)
+" %}
diff --git a/docs/site/migration/extensions.md b/docs/site/migration/extensions.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3955](https://github.com/strongloop/loopback-next/issues/3955)
+" %}
diff --git a/docs/site/migration/models/core.md b/docs/site/migration/models/core.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'Migrating model definitions and built-in APIs'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-models-core.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3718](https://github.com/strongloop/loopback-next/issues/3718).
+" %}
diff --git a/docs/site/migration/models/methods.md b/docs/site/migration/models/methods.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3949](https://github.com/strongloop/loopback-next/issues/3949).
+" %}
diff --git a/docs/site/migration/models/mixins.md b/docs/site/migration/models/mixins.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3951](https://github.com/strongloop/loopback-next/issues/3951)
+" %}
diff --git a/docs/site/migration/models/operation-hooks.md b/docs/site/migration/models/operation-hooks.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3952](https://github.com/strongloop/loopback-next/issues/3952)
+" %}
diff --git a/docs/site/migration/models/overview.md b/docs/site/migration/models/overview.md
@@ -0,0 +1,45 @@
+---
+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
+---
+
+**FIXME:** Explain at high level how to migrate models from a LB3 app to a LB4
+project. Refer to sub-sections for model details.
+
+In LoopBack 3, models are the cornerstone. They describe shape of data (schema),
+provide persistence-related behavior and implement public (REST) API. Besides
+this core functionality, there are many ways how to extend the built-in
+behavior.
+
+In LoopBack 4, many things changed but some remain the same. A model class is no
+longer responsible for everything. We have Models to describe shape of data,
+Repositories to provide persistence-related behavior and finally Controllers to
+implement public APIs. Under the hood, repositories are re-using a lot of the
+same persistence implementation you may know from LoopBack 3, therefore some
+concepts remain unchanged.
+
+To make the migration guide easier to navigate, we split model-related
+instructions into several sub-sections.
+
+1. [Migrating model definitions and built-in APIs](./core.md) describes how to
+   migrate the core of your Models - the model definition, persistence behavior
+   and public API provided by the framework itself.
+
+2. [Migrating model relations](./relations.md) explains how to migrate
+   relations, from the definition of a relation to its public APIs.
+
+3. [Migrating custom model methods](./methods.md) show how to bring over custom
+   methods that are enhancing models with new functionality, adding to the
+   features provided by the framework.
+
+4. [Migrating remoting hooks](./remoting-hooks.md) explains how to migrate hooks
+   that are executed by the REST API layer.
+
+5. [Migrating CRUD operation hooks'](./operation-hooks.md) shows how to migrate
+   hooks (observers) that are executed by the persistence layer.
+
+6. [Migrating model mixins](./mixins.md) provides instructions for migrating
+   mixins - small components that can enhance Model schema, behavior, or both.
diff --git a/docs/site/migration/models/relations.md 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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3948](https://github.com/strongloop/loopback-next/issues/3948).
+" %}
diff --git a/docs/site/migration/models/remoting-hooks.md b/docs/site/migration/models/remoting-hooks.md
@@ -0,0 +1,13 @@
+---
+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
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3950](https://github.com/strongloop/loopback-next/issues/3950).
+" %}
diff --git a/docs/site/migration/mounting-lb3app.md b/docs/site/migration/mounting-lb3app.md
@@ -1,16 +1,19 @@
 ---
 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
-offers a way to mount your LoopBack 3 application in a LoopBack 4 project. By
-adding your application this way, the application's REST API is included in the
-OpenAPI spec provided by the LoopBack 4 application. This also means that the
-LoopBack 3 application's models can be used with the LoopBack 4 REST API
+Migrating from LoopBack version 3 to version 4 is a big task because so many
+things have changed between the versions. To make this process easier, we
+implemented a feature allowing users to run their existing LoopBack 3
+application as a component of the new LoopBack 4 project.
+
+By adding your application this way, the application's REST API is included in
+the OpenAPI spec provided by the LoopBack 4 application. This also means that
+the LoopBack 3 application's models can be used with the LoopBack 4 REST API
 Explorer.
 
 ## Mounting the LoopBack 3 Application in a LoopBack 4 Project
@@ -53,7 +56,8 @@ the rest routes. Default `mode` is the full application (`fullApp`).
 ```ts
 this.bootOptions = {
   lb3app: {
-    mode: 'restRouter', // only REST routes are mounted
+    // only REST routes are mounted
+    mode: 'restRouter',
   },
 };
 ```
@@ -66,7 +70,8 @@ you can modify the `path`. Default `path` is `../lb3app/server/server`.
 ```ts
 this.bootOptions = {
   lb3app: {
-    path: '../coffee-shop/server/server', // server file is found under this path
+    // server file is found under this path
+    path: '../coffee-shop/server/server',
   },
 };
 ```
diff --git a/docs/site/migration/not-planned.md b/docs/site/migration/not-planned.md
@@ -0,0 +1,13 @@
+---
+lang: en
+title: 'LoopBack 3 features not planned in LoopBack 4'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-not-planned.html
+---
+
+{% include note.html content="
+This is a placeholder page, the task of adding content is tracked by the
+following GitHub issue:
+[loopback-next#3956](https://github.com/strongloop/loopback-next/issues/3956)
+" %}
diff --git a/docs/site/migration/overview.md b/docs/site/migration/overview.md
diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
