Clarify docs dev process #809
Conversation
- Keeps docs authors safe as some OS have a very old Node version installed as system default which generate loads of errors on `npm install`. - Updating node automatically updates npm to a compatible version.
- Some authors will beneift from hints about the nvm/npm/node universe and explicit info about the website structure.
✅ Deploy Preview for dlt-hub-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| The website is a Node.js application. | ||
|
|
||
| The documentation is generated using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. | ||
| Docusaurus consumes content from the `./docs` folder (at `./docs/website/docs` in this repo). The content includes: |
There was a problem hiding this comment.
Also Docusaurus consumes content from the ./blog (./docs/website/blog), please mention this in the doc.
here is a generated blog: https://dlthub.com/docs/blog
There was a problem hiding this comment.
Thanks for adding that. Appended a line about blogs. It would be a bigger rewrite to generalise docs and blogs as 'website content`, so for now a shovel remains a shovel, not a digging implement.
| @@ -0,0 +1 @@ | |||
| engine-strict=true No newline at end of file | |||
There was a problem hiding this comment.
do we really need this? we don't fix npm version in package.json
There was a problem hiding this comment.
Node version range is already specified in package,json in the engines section. Upgrading node also upgrades its bundled npm, so pinning the node version indirectly pins the npm version too.
The reason for my change was that without the engine-strict=true it just produces a version warning. For me as a new Node user the warning was lost in a lot of other frightening output and it was not obvious that all I needed to do was upgrade Node. Even a recent edition of Ubuntu (22.04) only has Node 12.22, which is older than the package's required `>=16.14".
With engine-strict=true it simply refuses to install and succinctly tells the user that they need a later version of Node. The website README helps them get the latest stable version.
I have not considered how making it strict could affect broader CI/CD processes. Perhaps there are other parts of dlt that depend on Node? There could also be an assumed development environment - with a latest stable node version - that I'm not aware of.
Background info:
2 participants
Description
package.json, which also helps devs/authors get the right node version.Related Issues
Slack chat with Anton
Additional Context
Hopefully it will save new authors some time in their first contribution attempts.
Some authors will benefit from hints about the nvm/npm/node universe and explicit info about the website structure. Enforcing minimum Node version helps keep docs authors safe as some OS have a very old Node version installed as system default, which generate loads of errors on
npm install.