Issue 5560 - Specify the JSDoc dependency explicitly

package-lock.json

+{

[Sebastian Noack, 2017/08/30 18:36:24]

I wonder whether we should add package-lock.json to the repository, or rather
list it in .hgignore/.gitignore. While the official documentation recommends to
commit this file to your repository, I'm not convinced that freezing the whole
environment, pinning the version of each module in the dependency tree, is worth
it. Not to mention the additional boilerplate, and effort to keep all (indirect)
dependencies up-to-date.

[Wladimir Palant, 2017/08/30 18:50:01]

Initially, I wasn't sure either. However, you have to consider this: if we don't
pin the versions, we cannot really know which version buildtools users will
install. They might get a newer version of a module which introduces a subtle
incompatibility and results in a broken build. It's better to pin a known-good
state that we'll update explicitly when we feel like it, in the interest of
reproducible builds.

[Sebastian Noack, 2017/08/30 19:02:33]

I wouldn't mind pinning the version of JSDoc and webpack in package.json.
However, this is about pinning each of their dependencies as well. If JSDoc or
webpack require a specific version of a package this is already be handled in
their package.json file. Also note that we don't pin any or our Python
dependencies either. So even if in theory a minor version difference of a
dependency of webpack could result in slightly different builds, we still have
the same issue with our Python dependencies.

[tlucas, 2017/08/30 20:49:47]

Imho, the thing to consider is that a packages' package.json (which is beyond
our control) allows for non-pinned versions - that way, in theory, a major
version difference is also perfectly possible.

While quickly following down the current dependencies, jsdoc's package.json
allows patch updates of e.g. klaw, while klaw itself allows minor version
updates for e.g. graceful-fs. I'm not sure, however, if and in which way a
Node.js environment tends to break on updates of any degree.

Also imho, amending an autogenerated file is well worth the effort, when we get
a reproducible environment in return.

[kzar, 2017/08/31 10:54:35]

FWIW I am in favour of pinning dependencies where possible as well.

+  "name": "buildtools",
+  "requires": true,
+  "lockfileVersion": 1,
+  "dependencies": {
+    "babylon": {
+      "version": "7.0.0-beta.22",
+      "resolved": "https://registry.npmjs.org/babylon/-/babylon-7.0.0-beta.22.tgz",
+      "integrity": "sha512-Yl7iT8QGrS8OfR7p6R12AJexQm+brKwrryai4VWZ7NHUbPoZ5al3+klhvl/14shXZiLa7uK//OIFuZ1/RKHgoA=="
+    },
+    "bluebird": {
+      "version": "3.5.0",
+      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.5.0.tgz",
+      "integrity": "sha1-eRQg1/VR7qKJdFOop3ZT+WYG1nw="
+    },
+    "catharsis": {
+      "version": "0.8.9",
+      "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.8.9.tgz",
+      "integrity": "sha1-mMyJDKZS3S7w5ws3klMQ/56Q/Is=",
+      "requires": {
+        "underscore-contrib": "0.3.0"
+      }
+    },
+    "escape-string-regexp": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz",
+      "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ="
+    },
+    "graceful-fs": {
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.1.11.tgz",
+      "integrity": "sha1-Dovf5NHduIVNZOBOp8AOKgJuVlg="
+    },
+    "js2xmlparser": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-3.0.0.tgz",
+      "integrity": "sha1-P7YOqgicVED5MZ9RdgzNB+JJlzM=",
+      "requires": {
+        "xmlcreate": "1.0.2"
+      }
+    },
+    "jsdoc": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-3.5.4.tgz",
+      "integrity": "sha512-VmTw0J+2L16IxAe0JSDSAcH0F+DbZxaj8wN1AjHtKMQU/hO0ciIl5ZE93XqrrFIbknobuqHKJCXZj6+Hk57MjA==",
+      "requires": {
+        "babylon": "7.0.0-beta.22",
+        "bluebird": "3.5.0",
+        "catharsis": "0.8.9",
+        "escape-string-regexp": "1.0.5",
+        "js2xmlparser": "3.0.0",
+        "klaw": "2.0.0",
+        "marked": "0.3.6",
+        "mkdirp": "0.5.1",
+        "requizzle": "0.2.1",
+        "strip-json-comments": "2.0.1",
+        "taffydb": "2.6.2",
+        "underscore": "1.8.3"
+      }
+    },
+    "klaw": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/klaw/-/klaw-2.0.0.tgz",
+      "integrity": "sha1-WcEo4Nxc5BAgEVEZTuucv4WGUPY=",
+      "requires": {
+        "graceful-fs": "4.1.11"
+      }
+    },
+    "marked": {
+      "version": "0.3.6",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-0.3.6.tgz",
+      "integrity": "sha1-ssbGGPzOzk74bE/Gy4p8v1rtqNc="
+    },
+    "minimist": {
+      "version": "0.0.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.8.tgz",
+      "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0="
+    },
+    "mkdirp": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz",
+      "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=",
+      "requires": {
+        "minimist": "0.0.8"
+      }
+    },
+    "requizzle": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.1.tgz",
+      "integrity": "sha1-aUPDUwxNmn5G8c3dUcFY/GcM294=",
+      "requires": {
+        "underscore": "1.6.0"
+      },
+      "dependencies": {
+        "underscore": {
+          "version": "1.6.0",
+          "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.6.0.tgz",
+          "integrity": "sha1-izixDKze9jM3uLJOT/htRa6lKag="
+        }
+      }
+    },
+    "strip-json-comments": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
+      "integrity": "sha1-PFMZQukIwml8DsNEhYwobHygpgo="
+    },
+    "taffydb": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/taffydb/-/taffydb-2.6.2.tgz",
+      "integrity": "sha1-fLy2S1oUG2ou/CxdLGe04VCyomg="
+    },
+    "underscore": {
+      "version": "1.8.3",
+      "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.8.3.tgz",
+      "integrity": "sha1-Tz+1OxBuYJf8+ctBCfKl6b36UCI="
+    },
+    "underscore-contrib": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/underscore-contrib/-/underscore-contrib-0.3.0.tgz",
+      "integrity": "sha1-ZltmwkeD+PorGMn4y7Dix9SMJsc=",
+      "requires": {
+        "underscore": "1.6.0"
+      },
+      "dependencies": {
+        "underscore": {
+          "version": "1.6.0",
+          "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.6.0.tgz",
+          "integrity": "sha1-izixDKze9jM3uLJOT/htRa6lKag="
+        }
+      }
+    },
+    "xmlcreate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-1.0.2.tgz",
+      "integrity": "sha1-+mv3YqYKQT+z3Y9LA8WyaSONMI8="
+    }
+  }
+}