From 1ef5b1ca732bb0fea7ddd0ab88f6f1eddae1d2b3 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 +++
 docs/site/migration/auth/built-in.md          | 13 +++
 docs/site/migration/auth/oauth2.md            | 13 +++
 docs/site/migration/auth/overview.md          | 28 +++++++
 docs/site/migration/auth/passport.md          | 13 +++
 docs/site/migration/boot-scripts.md           | 13 +++
 docs/site/migration/cli.md                    | 13 +++
 docs/site/migration/clients.md                | 13 +++
 docs/site/migration/datasources.md            | 13 +++
 docs/site/migration/express-middleware.md     | 13 +++
 docs/site/migration/extensions.md             | 13 +++
 docs/site/migration/models/core.md            | 13 +++
 docs/site/migration/models/methods.md         | 13 +++
 docs/site/migration/models/mixins.md          | 13 +++
 docs/site/migration/models/operation-hooks.md | 13 +++
 docs/site/migration/models/overview.md        | 45 ++++++++++
 docs/site/migration/models/relations.md       | 13 +++
 docs/site/migration/models/remoting-hooks.md  | 13 +++
 .../mounting-lb3app.md}                       | 25 +++---
 docs/site/migration/not-planned.md            | 13 +++
 docs/site/migration/overview.md               | 76 +++++++++++++++++
 docs/site/sidebars/lb4_sidebar.yml            | 84 +++++++++++++++++--
 22 files changed, 461 insertions(+), 15 deletions(-)
 create mode 100644 docs/site/Migrating-from-LoopBack-3-redirect.md
 create mode 100644 docs/site/migration/auth/built-in.md
 create mode 100644 docs/site/migration/auth/oauth2.md
 create mode 100644 docs/site/migration/auth/overview.md
 create mode 100644 docs/site/migration/auth/passport.md
 create mode 100644 docs/site/migration/boot-scripts.md
 create mode 100644 docs/site/migration/cli.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} (73%)
 create mode 100644 docs/site/migration/not-planned.md
 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/auth/built-in.md b/docs/site/migration/auth/built-in.md
new file mode 100644
index 000000000000..6c7e822511d4
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..5c700872ef8f
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..3ab4007e35b8
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..82b25fb8b735
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..e9a1f959c1f7
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..cf650b86214a
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..d7441269010d
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..cff5b13545ce
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..e282741fba84
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..28313435d179
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..59bdefaa5d76
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..9e5d5cd6cd1a
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..430a83877b0f
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..9896b070920d
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..dc07414083d1
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..e67ae2d37729
--- /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
+---
+
+{% 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
new file mode 100644
index 000000000000..eeb758491485
--- /dev/null
+++ 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/Migrating-from-LoopBack-3.md b/docs/site/migration/mounting-lb3app.md
similarity index 73%
rename from docs/site/Migrating-from-LoopBack-3.md
rename to docs/site/migration/mounting-lb3app.md
index 7f27c9457560..56458f5ecd2c 100644
--- a/docs/site/Migrating-from-LoopBack-3.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
new file mode 100644
index 000000000000..aae6476e7c28
--- /dev/null
+++ 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
new file mode 100644
index 000000000000..e457d4b83e0e
--- /dev/null
+++ b/docs/site/migration/overview.md
@@ -0,0 +1,76 @@
+---
+lang: en
+title: 'Migration guide'
+keywords: LoopBack 4.0, LoopBack 4, LoopBack 3, Migration
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/migration-overview.html
+---
+
+As mentioned elsewhere in the documentation, we wrote LoopBack 4 from the ground
+up and therefore the migration requires more effort than in previous major
+versions. The migration guide presented in the nested pages describe steps to
+migrate various features used by typical LoopBack 3 applications.
+
+Unless your project is very small, upgrading everything in one go is most likely
+not feasible. It would require too much time and introduce too many breaking
+changes to consumers of your API.
+
+We are recommending the following incremental approach:
+
+1. Before you start, learn more about the differences between LoopBack versions
+   3 and 4 and build a good understanding of how LoopBack 3 concepts are
+   translated to LoopBack 4. See
+   [Understanding the differences between LoopBack 3 and LoopBack 4](../Understanding-the-differences.md).
+
+2. Start with mounting your existing LoopBack 3 application in a new LoopBack 4
+   project, as described in
+   [Mounting a LoopBack 3 application](mounting-lb3app.md). This will allow you
+   to build new features in LoopBack 4, while keeping your existing APIs
+   unchanged.
+
+3. Next migrate your global (application-level) Express middleware, so that both
+   your old and your new APIs can use the same set of middleware. Learn more in
+   [Migrating Express middleware](express-middleware.md).
+
+4. Before you can define new models (or import existing ones), you need
+   datasources to attach them to. Follow the steps in
+   [Migrating datasources](datasources.md) to bring them over to LoopBack 4.
+
+5. With this setup in place, it's time to migrate models. In theory, you can
+   migrate models one-by-one, but in practice you will need to migrate related
+   models together. We have a dedicated section for model migration, start with
+   the overview in [Migrating models](models/overview.md).
+
+Besides models and their APIs, there are few more LoopBack 3 features that
+require migration:
+
+1. In LoopBack 3, boot scripts allow the application to run custom code at
+   startup. In LoopBack 4, [Lifecycle observers](../Life-cycle.md) allow
+   application to run code not only at startup, but also before shutting down.
+   Learn how to convert your boot scripts to lifecycle observers in
+   [Migrating boot scripts](boot-scripts.md).
+
+2. To make your application secure, LoopBack 3 offers several ways how to
+   implement authentication and authorization. Check out
+   [Authentication & authorization](auth/overview.md) for an overview and links
+   to further resources.
+
+3. LoopBack version 4 has its own CLI tool `lb4` (see
+   [Command-line interface](../Command-line-interface.md)). We preserved many of
+   the commands you are familiar with in `lb` from LoopBack 3, but some of them
+   are different in version 4. Learn more in
+   [Migrating CLI usage patterns](cli.md).
+
+4. LoopBack 4 introduced a very different programming model for components and
+   extensions. If you are maintaining or using LoopBack 3 components, then you
+   should read [Migrating components and extensions](extensions.md).
+
+5. There are several client SDKs for LoopBack 3 that make it easier for
+   different clients to consume REST APIs provided by LoopBack applications.
+   Please refer to [Migrating clients](clients.md) to learn how to upgrade
+   clients built using the SDKs.
+
+Last but not least, we took the opportunity presented by this big release to
+abandon certain features and components that we don't have bandwidth to maintain
+and improve going forward. Learn more in
+[LoopBack 3 features not planned in LoopBack 4](not-planned.md).
diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
index f9d672fda331..52ec589acfd5 100644
--- a/docs/site/sidebars/lb4_sidebar.yml
+++ b/docs/site/sidebars/lb4_sidebar.yml
@@ -620,17 +620,91 @@ 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:
 
-  - title: 'Understanding the differences between LoopBack 3 and LoopBack 4'
+  - title: 'Understanding the differences'
     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: 'Express middleware'
+    url: migration-express-middleware.html
+    output: 'web, pdf'
+
+  - title: 'Datasources'
+    url: migration-datasources.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-auth-overview.html
+    output: 'web, pdf'
+    children:
+
+    - title: 'Built-in models'
+      url: migration-auth-built-in.html
+      output: 'web, pdf'
+
+    - title: 'Passport'
+      url: migration-auth-passport.html
+      output: 'web, pdf'
+
+    - title: 'OAuth2 Provider'
+      url: migration-auth-oauth2.html
+      output: 'web, pdf'
+
+  - title: 'CLI'
+    url: migration-cli.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: 'Features not planned'
+    url: migration-not-planned.html
     output: 'web, pdf'
 
 - title: 'Best practices'