Rework README, add info from docs site

[bajtos]

Rework the initial section, simplify warnings and installation
instructions.

I decided to remove the "engine-strict" recommendation, as Node v0.10/v0.12 are no longer supported under the LTS plan, therefore I think it's unlikely there will be people running on these ancient versions and wanting to use the new loopback-context.

Update the "Usage" section with content from docs site, as was found in
Using-current-context.md.

@crandmck @josieusa PTAL
cc @superkhau

[josieusa]

Thanks for asking me to take a look.
LGTM.
Just one note, though. It seems to me that the README doesn't explain clearly enough that the syntax to enable the HTTP context is the following:

...
"initial": {
  ...
  "loopback-context#per-request": {
    "params": {
      "enableHttpContext": true
    }
  }
},
...

Mind the params field.

[bajtos]

@josieusa good point! I added an example configuration - see a5793a5.

[crandmck]

Make sure you are running on a Node version supported by this module!

We should state what these are, rather than leaving it up to the user to figure it out for themselves. Either state the versions or say that it's the Node versions supported by LoopBack.

Otherwise, LGTM.

[bajtos]

Make sure you are running on a Node version supported by this module!

We should state what these are, rather than leaving it up to the user to figure it out for themselves. Either state the versions or say that it's the Node versions supported by LoopBack.

@crandmck my concern is that the supported versions are maintained in package.json and if we duplicate the information in README, then we will likely forget to update README together with package.json and thus README will eventually get outdated.

loopback-context may support a smaller set of Node versions than LoopBack does.

Thoughts?

[superkhau]

Maybe recommend strong-pm first?

[superkhau]

},

[superkhau]

Here is a snippet using a middleware..
The following is an example of using a middleware...

[superkhau]

...likely forget to update README together with package.json and thus README will eventually get outdated.

IMO, it is better to be clear than to leave the docs ambiguous (I agree with @crandmck on this point, we should favour the end user experience over our laziness to maintain the docs). I agree with you though they will get outdated over time, but we can simply update it when a user complains/creates an issue at that time.

An alternative solution is maybe link directly to the line in package.json from the README?

[crandmck]

An alternative solution is maybe link directly to the line in package.json from the README?

Perhaps some combo of the two, i.e. state the specific Node versions in the README, and say something like "if you encounter problems, check package.json to ensure you're using a supported Node version".

[josieusa]

Or, since Loopback docs are now open source, and are supposed to be quite up-to-date, list the versions there, and in the README you can just remind the user to read the docs.

[bajtos]

Or, since Loopback docs are now open source, and are supposed to be quite up-to-date, list the versions there, and in the README you can just remind the user to read the docs.

@josieusa hey, thank you for chiming in! Since loopback-context is deprecated, the docs on loopback.io will no longer mention this module. That's one of the reasons why I am moving the content from loopback.io to this README.

Perhaps some combo of the two, i.e. state the specific Node versions in the README, and say something like "if you encounter problems, check package.json to ensure you're using a supported Node version".

If the user is using an unsupported Node.js versions, npm install will print either an error or a warning (depending on their configuration of engine-strict) and AFAIK, these messages contain the Node.js versions required by the package.

My conclusion is that I am going to list the current supported versions in README, nothing more.