From 9d0002555df08addf99a058519bd8ce692ab8683 Mon Sep 17 00:00:00 2001
From: Tim van der Meij <timvandermeij@gmail.com>
Date: Sun, 16 Jun 2024 14:47:06 +0200
Subject: [PATCH] Implement reproducibility for the JSDoc builds

The JSDoc builds are currently not reproducible because a timestamp is
included in the output, meaning that two builds from identical source
code, made at different times, result in different output.

This is undesirable because it makes diffing the output difficult, for
instance recently during the Gulp 5 efforts, because the timestamp
differences are irrelevant and could obscure actually important
differences in the output during e.g. code changes. Moreover,
reprodicibility of build artifacts has become increasingly important;
please refer to the Reproducible Builds initiative at
https://reproducible-builds.org (note the "Why does it matter?" section
specifically) and https://reproducible-builds.org/docs/timestamps which
further explains the problem of timestamps in build artifacts.

This commit fixes the issue by configuring JSDoc to not include the
timestamps in the output. It's not relevant for end users and without it
the build is fully reproducible so that identical source code builds
result in bit-by-bit identical output artifacts.

Note that this option sadly can only be set via a configuration file,
and not via the command line parameters like we used to have, so for
consistency we also move the other options into the configuration file
so they are all in one place and the Gulpfile becomes a bit simpler.
---
 gulpfile.mjs | 10 +---------
 jsdoc.json   | 13 +++++++++++++
 2 files changed, 14 insertions(+), 9 deletions(-)
 create mode 100644 jsdoc.json

diff --git a/gulpfile.mjs b/gulpfile.mjs
index 06e3c61bc7a1b..7f2030dced6fb 100644
--- a/gulpfile.mjs
+++ b/gulpfile.mjs
@@ -1526,18 +1526,10 @@ gulp.task("jsdoc", function (done) {
   console.log();
   console.log("### Generating documentation (JSDoc)");
 
-  const JSDOC_FILES = ["src/display/api.js"];
-
   fs.rmSync(JSDOC_BUILD_DIR, { recursive: true, force: true });
   fs.mkdirSync(JSDOC_BUILD_DIR, { recursive: true });
 
-  const command =
-    '"node_modules/.bin/jsdoc" -d ' +
-    JSDOC_BUILD_DIR +
-    " " +
-    JSDOC_FILES.join(" ");
-
-  exec(command, done);
+  exec('"node_modules/.bin/jsdoc" -c jsdoc.json', done);
 });
 
 gulp.task("types", function (done) {
diff --git a/jsdoc.json b/jsdoc.json
new file mode 100644
index 0000000000000..357bac4a592b7
--- /dev/null
+++ b/jsdoc.json
@@ -0,0 +1,13 @@
+{
+  "source": {
+    "include": ["src/display/api.js"]
+  },
+  "opts": {
+    "destination": "build/jsdoc/"
+  },
+  "templates": {
+    "default": {
+      "includeDate": false
+    }
+  }
+}