docs(plugins): note side-effect when using await in fastify.register()

[andersonjoseph]

This PR adds documentation for a side effect of using await when registering a plugin in Fastify (#3863)

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[mcollina]

lgtm

[Uzlopak]

I have now more questions than before. I thought that awaiting the register call ensures, that we have no race conditions. I quite dont get, why awaiting it, results in "finalization" of the encapsulation.

[Fdawgs]

Have same concerns as @Uzlopak

[mcollina]

I have now more questions than before. I thought that awaiting the register call ensures, that we have no race conditions.

You are right, awaiting ensure that the plugin tree is fully registered. That's all it does.

I quite dont get, why awaiting it, results in "finalization" of the encapsulation.

I thought the term "finalization" was simpler for newbies. In practice, this means that all previous have been fully registered and you can't alter them (mostly, there are exceptions here).

[andersonjoseph]

yes, awaiting register doesn't finalize the encapsulation per se, but, it loads all the plugins that have been previously registered, so altering them after that doesn't have any effect (there are exceptions as @mcollina said)

I used "finalization of the encapsulation" as a simpler explanation of this behavior, and because it was used to explain it before.

[Uzlopak]

We have to come to a conclusion on what we want to express in the documentation. In this state we can not merge it.

[mcollina]

What do you propose?

[Uzlopak]

@mcollina
Maybe something like this?

*Note: Using await when registering a plugin loads the complete plugin and the underlying dependency tree and thus "finalizing" the encapsulation
process. Any mutations to the plugin-instance after the plugin and its dependencies are loaded will
not reflect in the parent instance.

[Uzlopak]

So the question is, does my suggestion pass the grandma test?

[mcollina]

@Uzlopak sgtm.

[Uzlopak]

@Fdawgs Lets approve and merge it ;)