fixup! add overview & placeholder pages

Signed-off-by: Miroslav Bajtoš <[email protected]>

docs/site/migration/auth/built-in.md

@@ -6,8 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-built-in.html
 ---
 
-TODO: explain how to migrate:
-
-- built-in models (User, AccessToken, ACL)
-- authentication
-- authorization
+{% 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)
+" %}

docs/site/migration/auth/oauth2.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-oauth2.html
 ---
 
-TODO: explain how to migrate apps using loopback-component-oauth2
+{% 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)
+" %}

docs/site/migration/auth/overview.md

@@ -6,8 +6,23 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-overview.html
 ---
 
-TODO: High-level description of the following migration steps:
+LoopBack version 3 provides several options for adding authentication and
+authorization to secure the applications:
 
-- built-in models (User, AccessToken, ACL), authentication & authorization
-- apps using loopback-component-passport
-- apps using loopback-component-oauth2
+- 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).

docs/site/migration/auth/passport.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-auth-passport.html
 ---
 
-TODO: explain how to migrate apps using loopback-component-passport
+{% 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)
+" %}

docs/site/migration/boot-scripts.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-boot-scripts.html
 ---
 
-TODO: Explain how to migrate LB3 boot scripts to LB4 LifeCycle observers.
+{% 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)
+" %}

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)
+" %}

docs/site/migration/clients.md

@@ -6,11 +6,8 @@ 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
+{% 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)
+" %}

docs/site/migration/datasources.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-datasources.html
 ---
 
-TODO: show how to migrate a datasource from a LB3 app to LB4.
+{% 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).
+" %}

docs/site/migration/express-middleware.md

@@ -6,5 +6,8 @@ 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.
+{% 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)
+" %}

docs/site/migration/extensions.md

@@ -6,5 +6,8 @@ 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.
+{% 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)
+" %}

docs/site/migration/models/core.md

@@ -1,15 +1,13 @@
 ---
 lang: en
-title: 'Migrating models'
+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
 ---
 
-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`.
+{% 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).
+" %}

docs/site/migration/models/methods.md

@@ -6,7 +6,8 @@ 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
+{% 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).
+" %}

docs/site/migration/models/mixins.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-models-mixins.html
 ---
 
-TODO: Explain how to migrate model mixins.
+{% 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)
+" %}

docs/site/migration/models/operation-hooks.md

@@ -6,4 +6,8 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-models-operation-hooks.html
 ---
 
-TODO: Explain how to migrate CRUD Operation Hooks.
+{% 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)
+" %}

docs/site/migration/models/overview.md

@@ -6,5 +6,40 @@ 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
+**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.

docs/site/migration/models/relations.md

@@ -6,8 +6,8 @@ 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)
+{% 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).
+" %}

docs/site/migration/models/remoting-hooks.md

@@ -6,11 +6,8 @@ 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 that data via Dependency Injection.
+{% 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).
+" %}

docs/site/migration/mounting-lb3app.md

@@ -6,11 +6,14 @@ sidebar: lb4_sidebar
 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',
   },
 };
 ```

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)
+" %}

docs/site/migration/overview.md

@@ -6,9 +6,71 @@ sidebar: lb4_sidebar
 permalink: /doc/en/lb4/migration-overview.html
 ---
 
-Migration guide from LoopBack 3 to LoopBack 4.
+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.
 
-TODO: explain the high-level plan for upgrading in incremental steps, point to
-sub-chapters for more details.
+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.
 
-List components & feature that are not planned for LB4.
+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).