Glossary: reproducible

https://nix.dev/glossary currently says:

Reproducibility would guarantee exactly the same results no matter when or on what machine you run the command.

I think this is not clear to everyone and maybe not actually what we mean when talking about nix and nixos. It might be true in the narrow context of software developers that work for a company that only use x86_64-linux systems, but the real world is more complex.

Since that page became authoritative terminology (with https://github.com/NixOS/nix.dev/issues/377) for the full project including documentation and i guess also public communication, we should review it to the same standard as the new definitions!

First, what does result mean?
Is it the binary package, the terminal output of a command or the function of a program?

In the context of the reproducible builds initiative, it means having bit-by-bit identical binary artifacts when building a package.

Since we use the same term on https://nixos.org/, i guess we agree on their definition.

https://reproducible-builds.org/docs/definition/

But this means, building a package for different architectures, you get a different artifact! So the program might also work differently.

So it is in conflict with our current definition here.

no matter [...] on what machine you run the command

We have an example here where the same definition is used:

https://github.com/NixOS/nix.dev/blob/master/source/tutorials/ad-hoc-developer-environments.md#towards-reproducibility

In that case, it matters on what machine i run the command!

On NixOS it will work, on macOS it might work, on a Linux on RISC-V it might not work and on Windows, it will not work (since Nix does not support it except through WSL).

I also miss that detail from the reproducible builds initiative definition. There are more systems than x86_64-linux!
In the software industry, most developers probably don't use Linux!
And with computer users even less.

So we can't really claim:

if a package works on one machine, it will also work on another

which is the core claim of the whole project and on https://nixos.org/.

People that look at the project for the first time and understand it often think "this sounds too good to be true" and i think we should be very honest about the limitations of our solution to not look like a scam.

What does "the command" mean here? The nix command or like in the linked example, git?
Can Nix really make every program reproducible? If i run a game, do i get the same score every time i play? (no, many programs don't function that way)

What do we really mean when we say reproducible?

I think a good metric would be that high level programmers like JavaScript and Ubuntu users should understand it.

We could also add more words, like declarative and reliable, that are prominently used on the website.

cc @fricklerhandwerk

Start with the glossary entry at https://nix.dev/glossary and compare it with the linked reproducible-builds.org definition and the “Towards reproducibility” section in source/tutorials/ad-hoc-developer-environments.md. Done means agreeing on a precise, project-wide definition of “reproducible” and updating the glossary and related wording to address the stated scope and limitations.