docs: add a skeleton of migration guide

[bajtos]

A skeleton of our migration guide, laying down the overall structure and creating placeholder pages that will be filled in later in follow-up pull requests.

Important: I am not aiming at covering all aspects of LB3 application development. This pull request is meant as the first step to allow incremental improvements in the (near) future.

Screenshot of the (final) sidebar

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[bajtos]

One thing I am debating with myself: should the sidebar entries start with Migrating prefix (e.g. Migrating datasources)? I find that very repetitive and prefer to leave that prefix out (e.g. Datasources nested inside Migration guide).

[richardpringle]

Can't wait to see those TODOs filled in 😉

[aharbis]

I find that very repetitive and prefer to leave that prefix out (e.g. Datasources nested inside Migration guide).

@bajtos I agree. I do not think it's necessary to prefix all entries with Migrating.

---

This is a great start to the migration guide! Speaking as someone who still has a large LoopBack 3 application that we still need to migrate, I feel this covers a large majority of the topics in question.

In LoopBack 3 we rely heavily on operation hooks and remote hooks to implement the vast majority of business logic (excluding of course remote methods). Understanding the life cycle differences between request processing in LoopBack 3 and LoopBack 4 is I think a critical point that many would benefit from.

[bajtos]

@aharbis thank you for the feedback.

Understanding the life cycle differences between request processing in LoopBack 3 and LoopBack 4 is I think a critical point that many would benefit from.

This is a great suggestion. Can you please open a new issue where we can discuss further details?

[emonddr]

One thing I am debating with myself: should the sidebar entries start with Migrating prefix (e.g. Migrating datasources)? I find that very repetitive and prefer to leave that prefix out (e.g. Datasources nested inside Migration guide).

Each subtopic of the Migration Guide (parent topic) in the sidebar should avoid using 'Migrating' over and over. But if the user does navigate to 'Migration Guide -> Models , for example, the title of that document should be "Migrating Models". Just so it is clear what the intention of the document is; especially if user performs a search on "Models" and ends up on that page...it should be clear that the purpose is migrating models as opposed to creating models.

[dhmlau]

LGTM. There are 2 questions that show up from time to time, I wonder if it is covered by the current plan.

1. can we continue to use loopback-component-storage in LB4?
2. can we continue to use the LoopBack supported connectors in LB4?
   For the database connectors, we probably don't need a section because it is supposed to continue to work. So maybe we add a note somewhere to make sure we state that?

[dhmlau]

LGTM with 2 questions in #3922 (comment).

[bajtos]

@dhmlau

LGTM. There are 2 questions that show up from time to time, I wonder if it is covered by the current plan.

Good questions! I can cover them in the overview document.

1. can we continue to use loopback-component-storage in LB4?

No, this is also mentioned in "Understanding the differences".

It makes me wonder: should we create a dedicated page to list all components & features that we don't plan to migrate to LB4?

2. can we continue to use the LoopBack supported connectors in LB4?
   For the database connectors, we probably don't need a section because it is supposed to continue to work. So maybe we add a note somewhere to make sure we state that?

I think the best place for this information is the page describing how to migrate datasources.

I can also add a short mention to the migration overview.

[dhmlau]

It makes me wonder: should we create a dedicated page to list all components & features that we don't plan to migrate to LB4?

+1. It would be even better if we provide the alternatives.

[raymondfeng]

It's a great list that covers most of LB3 features.

Maybe add one section to cover some of the lb CLI commands, such as lb swagger and lb soap.

[bajtos]

I addressed the review comments above, added text to overview pages, created follow-up issues and updated placeholder pages with links.

The pull request is ready for final review & landing.

@raymondfeng @dhmlau @emonddr @strongloop/sq-lb-apex PTAL.

[bajtos]

(I'll clean up the commit history after the changes are approved.)

[agnes512]

I like how migration/overview.md guilds LB3 users to migrate to LB4 by learning the differences and the limitations step by step.

[bajtos]

The test failures are unrelated to my changes, it looks like the US Census geocoding service is not available (hopefully only temporarily).

Cannot proxy GET https://geocoding.geo.census.gov/geocoder/locations/onelineaddress?format=json&benchmark=Public_AR_Current&address=1%20New%20Orchard%20Road%2C%20Armonk%2C%2010504.
RequestError: Error: getaddrinfo ENOTFOUND geocoding.geo.census.gov