From 76c218dc0ea83e47dcc3bf947f0a7f07be03927e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Thu, 4 Jun 2020 14:20:39 +0200 Subject: [PATCH] docs: add a new section on content organization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Miroslav Bajtoš --- docs/site/DEVELOPING.md | 63 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/site/DEVELOPING.md b/docs/site/DEVELOPING.md index 9ff5b4f57992..fc8c5973a9f6 100644 --- a/docs/site/DEVELOPING.md +++ b/docs/site/DEVELOPING.md @@ -286,6 +286,69 @@ LoopBack 4 documentation is hosted inside this monorepo in the This allows us to change both implementation and the documentation in a single pull request. +### Organization of content + +LoopBack 4 has a highly modular design, the codebase is organized into dozens of +packages. This arrangement provides great flexibility for package consumers, +supporting many different ways how to compose individual packages into larger +blocks. However, the growing number of packages also increases the complexity +for LoopBack users, as they need to know which packages to choose and how to use +them. As a result, the learning curve becomes very steep for new developers +coming to LoopBack. Newcomers get quickly overwhelmed by the amount of concepts +they need to understand and the different packages they need to know about. + +To prevent cognitive overload, we have categorized all monorepo packages into +two groups: + +1. Foundation-level packages are lower-level packages that are typically not + consumed by LoopBack applications directly. Instead, there are higher-level + packages exposing the functionality and/or the public API of these building + blocks. + + Examples: + + - `@loopback/core` is re-exporting all public API provided by + `@loopback/context`. + + - `@loopback/rest` is internally using `@loopback/http-server` to manage the + life cycle of an HTTP server. + +2. Framework-level packages are used directly by LoopBack applications and + provide API that LoopBack consumers use. + +The rule of thumb: a lower-level package is considered as foundation-level if + +- a higher-level package is re-exporting all public APIs of the lower-level + package (e.g. `@loopback/core` re-exports `@loopback/context`); or + +- another package is using the lower-level package as a implementation building + block (e.g. `@loopback/rest` uses `@loopback/express`). + +In our documentation, CLI templates and example applications, you should always +refer to framework-level packages. + +Foundation-level packages should have their own documentation describing how to +use the package independently of LoopBack, for example in their `README.md` file +or in a dedicated section of [loopback.io](https://loopback.io). + +#### Foundation-level packages + +List of packages that are considered as building blocks: + +- [packages/context](https://github.com/strongloop/loopback-next/tree/master/packages/context) +- [packages/express](https://github.com/strongloop/loopback-next/tree/master/packages/express) +- [packages/http-server](https://github.com/strongloop/loopback-next/tree/master/packages/http-server) +- [packages/metadata](https://github.com/strongloop/loopback-next/tree/master/packages/metadata) +- [packages/openapi-v3](https://github.com/strongloop/loopback-next/tree/master/packages/openapi-v3) +- [packages/repository-json-schema](https://github.com/strongloop/loopback-next/tree/master/packages/repository-json-schema) + +#### Framework-level packages + +All packages not listed above are considered as framework-level. + +We consider utilities like `@loopback/testlab` and example projects like +`@loopback/todo` as framework-level too. + ### Publishing changes To prevent documentation changes going live before the changes in the