Optionally suppress version number comments (allow deterministic builds)

[chromatic]

I originally filed this ticket with Pod-Simple (#148).

I'm working on a system to produce reproducible builds. When a Perl distribution's build process uses Pod::Man to produce man pages, a comment in the output includes the version numbers of both Pod::Simple and Pod::Man. Even if the contents of the file are otherwise the same, the output is different because of this comment.

For example, when building Mojolicious, the generated output for binaries such as morbo includes:

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================

I'd like to find a way to suppress either the version numbers in this output or this output entirely. This would let me consolidate output where it's otherwise identical. (If there are differences in the generated output outside of comments because of differences in versions of the Pod stack, that's fine.)

I prefer to set an environment variable or make another configuration in my build environment rather than pass an argument directly to any build command.

I'm happy to discuss this further as it's helpful.

[rra]

Yup, I can definitely do that. Do you have a standard environment variable that you use for things like that in reproducible builds? Adding those versions by default is a requirement on the Perl POD ecosystem side, so I'd want to disable it conditionally based on whether an environment variable is set, and ideally would prefer to use a standardized environment variable similar to what we did with SOURCE_DATE_EPOCH.

[chromatic]

Good question! Let me discuss with my team. I think something along the lines of PERL_REPEATABLE_BUILDS or something otherwise semantically meaningful would be appropriate. It's a bit verbose, but it's unlikely to conflict with anything else in the system. Do you have any preferences yourself?

[rra]

No strong preferences here. Pod::Man already supports one environment variable with a POD_MAN prefix, but I suspect that's too specific since you may want this to affect other things as well.

It's worth noting that lots of things that aren't Perl (such as OpenSSL, last I checked) use Pod::Man to generate man pages because people prefer to write them in POD, so there's an argument for an environment variable starting with POD_ instead. But that then wouldn't encompass other non-POD stuff in the Perl ecosystem, so there's a trade-off there.

[rra]

Just checking in on this again. Did you reach any consensus for what to call this environment variable?

[rra]

I'm willing to do this but want to be sure that it's still of interest before I take on the long-term support requirement, and would also strongly prefer someone working on reproducible builds to pick some standard name for this environment variable that can be used for other software as well. I'll leave this bug report open without taking action on it for the time being.

[rra]

After some discussion on pod-people, there doesn't seem to be much support for keeping the requirement in perlpodspec that formatters embed their version number in a comment. I'm looking at changing perlpodspec to remove that requirement, and then will likely remove these versions by default and add a flag to request that information be added if wanted.