Updating generated docs and README instructions for running doc server #501
Conversation
Shout out to @caseywatts for the PR #272. Better late than never.
| @@ -51,7 +51,7 @@ | |||
| "babel-eslint": "^10.0.1", | |||
| "eslint": "^5.9.0", | |||
| "jest": "^26", | |||
| "jsdoc": "^3.4.0", | |||
| "jsdoc": "3.6.7", | |||
There was a problem hiding this comment.
Is there a reason to not keep the caret here? 🤔
There was a problem hiding this comment.
jsdoc 3.6.8 was updated to use a version of the klaw library that's incompatible with node versions < 14.4.0, and this caused the jscodeshift CI builds to break when being run for node version 12. This is why the exact version of 3.6.7 is being used.
There was a problem hiding this comment.
Probably good to create an issue in the jsdoc repo and keep track of it in this repo too. 🤔
There was a problem hiding this comment.
It's a known issue.
JSDoc makes use of klaw, which decided to having breaking changes with 4.1
https://github.com/jprichardson/node-klaw/blob/master/CHANGELOG.md
I can put in an issue for it. Mainly just a reminder to bump up the version of JSDoc whenever node < v13 is deprecated from jscodeshift.
There was a problem hiding this comment.
@MichaelDeBoey I personally don't like the caret as people are bad at determining if a change is breaking or not. Since you can directly import any file from an npm module, there's a lot of stuff that can be a breaking change.
The tilde (allow patch updates only) is a bit better, but in this case it'd break things.
There was a problem hiding this comment.
Filed issue #502 to remind us to bump up whenever node < 14 is deprecated (which will probably be a while)
There was a problem hiding this comment.
@Daniel15 I agree not everybody adheres semver very good, but that shouldn't let us discard carets imo.
If a package has a lot of breaking non-major changes, we should either use strict version for that package or use another package that doesn't have these problems imo.
Using strict versions of dependencies can lead to multiple versions of the same package, while npm/Yarn could probably dedupe them and give you a much smaller node_modules.
You can indeed import any file from the package, but if you're using non-public API and it breaks, that's on you imo as the package was never intended to be used like that.
|
Looks good. Thanks :) |
Updating the generated jsdocs that had been sitting around unupdated for years. Also updated jsdoc dependency to 3.7; 3.4 had been causing crashes when
npm run docswas run. Also added to README casey's instructions about how to run the doc server.Shout out to @caseywatts for the PR #272. Better late than never.
@trivikr @Daniel15