Implement reproducibility for the JSDoc builds #18256
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
|
Before this patch, on the current I have triggered two builds from the same source code, moved the output into separate folders, computed the combined SHA256 hash of all files and generated the recursive diff. Note that the SHA256 hashes are different and the diff includes only timestamp changes. I have repeated this process with this patch applied below. Note that the SHA256 hashes are equal now and the diff is empty: |
|
/botio-linux preview |
From: Bot.io (Linux m4)ReceivedCommand cmd_preview from @timvandermeij received. Current queue size: 0 Live output at: http://54.241.84.105:8877/7c1af6f3258bc9f/output.txt |
From: Bot.io (Linux m4)SuccessFull output at http://54.241.84.105:8877/7c1af6f3258bc9f/output.txt Total script time: 0.98 mins Published |
|
Note that the only observable difference in the API documentation is that http://54.241.84.105:8877/7c1af6f3258bc9f/api now only shows |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.