Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update man page generation to respect SOURCE_DATE_EPOCH #7397

Open
wants to merge 1 commit into
base: latest
Choose a base branch
from

Conversation

andrin-geiger
Copy link

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.

@andrin-geiger andrin-geiger requested a review from a team as a code owner April 21, 2024 20:02
@wraithgar
Copy link
Member

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

@andrin-geiger
Copy link
Author

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
Copy link
Member

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
Copy link
Contributor

lukekarrys commented Apr 22, 2024

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
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants