`lib.trivial.revisionWithDefault` will change with every Git commit, which causes the manual to be rebuilt on every since PR.
Using `nixpkgs.rev` (or the dummy value "master" if it's not present) means that the manual will contain the revision if built on Hydra, but will not otherwise.
Why?
1. https://hydra.nixos.org/jobset/nixos/trunk-combined#tabs-configuration shows that `pkgs/top-level/release.nix` is passed the `nixpkgs` attrset, which is a "Git checkout".
2. Git checkouts come from [`builtins.fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins#builtins-fetchGit) and include the `rev` attribute.
3. The `rev` attribute is what `lib.trivial.revisionWithDefault` would have returned.
So, using `nixpkgs.rev or "master"` exclusively will cause the rebuilds on every commit to cease, but will allow "official" nixpkgs manual built on Hydra to continue to reference a specific commit.
every other format is deprecated, so to imply that people should be setting it is misleading
(`pyproject = true` should also go away eventually, but is the way until
then)
so that meta.description examples shown in the documentation
align with recommendations given in the "Meta attributes" section
in pkgs/README.md.
The changes were made with the following commands:
nix run nixpkgs#silver-searcher -- -l0 'description\s*=\s*"([Aa]n?|[Tt]he)\s' doc \
| xargs -0 nix run nixpkgs#gnused -- -i '' -Ee '/description/s/"([Aa]n?|[Tt]he)\s(.)/"\U\2/'
nix run nixpkgs#silver-searcher -- -l0 'description\s*=\s*".*\."' doc \
| xargs -0 nix run nixpkgs#gnused -- -i '' -Ee '/description/s/\."/"/'
Problem: `nix-build doc` gives a bunch of warnings because it inspects
`lib` to figure out where all the symbols are.
Solution: Move the step of figuring out where the symbols are to
a Nix evaluation inside a derivation instead.
Running the `update.py` script directly doesn't work anymore, so instead
replace all usages of it in the documentation with `nix-shell -p
vimPluginsUpdater --run 'vim-plugins-updater'`.
`mkComposerRepository` required `pname` and `version` since the beginning
(b36ad2f517), with the boolean attribute
becoming required later (3eb168da92).
For whatever reason `zip` in this case doesn't seem to be respecting the
`$TMP` or `$TMPDIR` variables, resulting in a permission denied error on
Darwin when sandbox is enabled.
The `-b` flag allows one to manually specify a tempdir, which allows the
build to succeed in spite of sandboxing.
Fixes https://github.com/NixOS/nixpkgs/issues/326380
