Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add a new section on content organization #5659

Merged
merged 1 commit into from
Jun 9, 2020
Merged

docs: add a new section on content organization #5659

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions docs/site/DEVELOPING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And the rest are framework-level pacakges? If yes, we should mention that, else it feels like the list of framework-level pacakges is missing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 69dcaa6

There is one thing that bugs me a bit: we also have utility packages like @loopback/build or @loopback/testlab that are technically not part of the framework, but they are not building blocks either in the sense that they should be mentioned in our framework documentation.

I guess "framework-level" is not the best term to use. Can we come up with a more accurate name?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about the extensions and examples packages? Those seem more like an adds-on.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about the extensions and examples packages? Those seem more like an adds-on.

Sure 👍

What I am trying to accomplish here is to distinguish between "building blocks" packages that should not be referred to in our docs, CLI templates and example apps; and everything else.

I used the term "framework-level" for "everything else", which is clearly misleading based on your feedback.

So, what would be a better term?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess "framework-level" is not the best term to use. Can we come up with a more accurate name?

They need not belong in the framework packages. They can be classified as helper/utility packages.

Copy link
Member Author

@bajtos bajtos Jun 8, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am adding the following clarification to the docs:

#### 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We consider utilities like @loopback/testlab and example projects like
@loopback/todo as framework-level too.

Doesn't feel right. Anything that LoopBack developers would not (maybe even never) use in their project feels very odd to be classified under framework-level packages. We need a third category - helpers, utility, along that line.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this is subjective.

Let's land my PR as the first step, and then you can open a follow-up PR to discuss how to improve this initial categorization.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good.


- [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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about this one either:

"dependencies": {
    "@loopback/core": "^2.7.1",
    "@loopback/repository-json-schema": "^2.4.3",
}

- [packages/repository-json-schema](https://github.com/strongloop/loopback-next/tree/master/packages/repository-json-schema)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This package depends on @loopback/core and @loopback/repository. It should be moved out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This package depends on @loopback/core and @loopback/repository. It should be moved out.

Please note the criteria is not whether a package depends on something else from @loopback/* namespace, but whether LB application developers should depend on that package directly.

Both @loopback/repository-json-schema and @loopback/openapi-v3 are not meant to be used directly. They are building blocks used by @loopback/rest. Applications are importing their APIs and functionality from @loopback/rest, as can be seen e.g. in examples/todo/src/controllers/todo.controller.ts


#### 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
Expand Down