feat(docs): migration guide for model relations

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

docs/site/migration/models/relations.md

@@ -6,8 +6,66 @@ 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).
-" %}
+When you define a relation in a LoopBack 3 model JSON file, the framework will
+create the following artifacts for you automatically:
+
+- Relation metadata defining the target model, foreign key column/property, and
+  so on.
+- Repository-like methods for accessing related model instance(s), for example
+  `Category.prototype.products`.
+- An inclusion resolver to allow clients to request relation traversal in
+  queries and include related models, e.g.
+  `Product.find({include: ['category']})`
+- REST API endpoints for querying a modifying models on the other side of the
+  relation, e.g. `GET /api/categories/1/products`.
+
+In LoopBack 4, these building blocks are typically provided by the application
+developer.
+
+- Relation metadata is defined via model decorators like `@hasMany`.
+- Relation repositories implement APIs for accessing and modifying data of
+  related models.
+- Inclusion resolvers implement relation traversal in queries.
+- Code-generated relation controllers implement REST APIs for model relations.
+
+At the moment, all of these artifacts must be created manually by the
+application developer. This gives developers a lot of power and flexibility in
+customizing the default behavior offered by the framework.
+
+In the future, we would like to provide declarative approach for building model
+relations, where the developer defines relation metadata and the framework
+builds all required artifacts at runtime, similarly to how LoopBack 3 works. You
+can join the discussion in the GitHub issue
+[loopback-next#2483](https://github.com/strongloop/loopback-next/issues/2483).
+
+## Migration path
+
+Follow these steps to migrate a model relation from LoopBack 3 to LoopBack 4:
+
+1. Run `lb4 relation` to define the model relation in your model class, generate
+   code for the relation repository and optionally register inclusion resolver.
+
+2. TBD, `lb4 relation` does not work for me!
+
+## Relation support
+
+The following relations are supported by LoopBack 4 and can be migrated from
+LoopBack 3:
+
+- [HasMany](../../HasMany-relation.md)
+- [HasOne](../../hasOne-relation.md)
+- [BelongsTo](../../BelongsTo-relation.md)
+
+Other relations types are not supported, you can subscribe to our progress in
+the high-level tracking issue
+[loopback-next#1450](https://github.com/strongloop/loopback-next/issues/1450)
+and issues for individual relation types:
+
+- HasManyThrough -
+  [loopback-next#2264](https://github.com/strongloop/loopback-next/issues/2264)
+- HasAndBelongsToMany -
+  [loopback-next#2308](https://github.com/strongloop/loopback-next/issues/2308)
+- Polymorphic relations -
+  [loopback-next#2487](https://github.com/strongloop/loopback-next/issues/2487)
+- ReferencesMany -
+  [loopback-next#2488](https://github.com/strongloop/loopback-next/issues/1450)