docs: update man page generation to respect SOURCE_DATE_EPOCH

[andrin-geiger]

SOURCE_DATE_EPOCH allows setting timestamps to the last time of modification in the source code rather than build time.
Currently the generated man pages are not fully reproducible because of the timestamp in these man pages.
Because the man pages have a coarse-grained timestamp (month year) this can go unnoticed, unless building in a different month/year.
Remark-man supports setting the date but uses new Date() by default.

[wraithgar]

I'm not sure what problem this is solving. Do we have timestamps in our docs somewhere that are wrong?

[andrin-geiger]

So currently the generated man pages always show the month and year of when these docs were generated.
When someone generates these docs in different months but uses the exact same source, the resulting docs are not bit-by-bit identical.

-.TH "NPM" "1" "March 2024" "" ""
+.TH "NPM" "1" "April 2024" "" ""

Using SOURCE_DATE_EPOCH allows setting the timestamp to the last modification of the source code.
This is especially useful for linux distributions which do continuous testing for reproducibility such as debian and arch.
If the SOURCE_DATE_EPOCH environment variable is not set, new Date() will be used.

[wraithgar]

Is there some other issue out there showing that folks are experiencing this issue? npm builds these docs as part of the release process so the date being current is correct behavior.

[lukekarrys]

It would be nice if our man files didn't churn based on when they were built. Eg when PRs to node fall on the next month, every man file gets updated.

I don't know what correct behavior is for man pages, but when I setup the man page generation I didn't know there was another way to do it.

My concern with this PR is that I don't know how to set that env var on my machine or in CI. To land this I would want to go fully towards the "reproducible builds" side and never fallback to new Date(). Is that possible with some standard tooling?

[lukekarrys]

According to one source the date should be The date of the last nontrivial change that was made to the man page.

I would be open to using SOURCE_DATE_EPOCH and then falling back to the mtime of the associated docs/content/**/*.md file.