nixos/doc/md-to-db.sh: consistent pandoc version #168598
Conversation
Until now, this script has used the version of pandoc from unstable. This means that running the script on the same version of Nixpkgs could produce different results, and meant that when Pandoc's output was changed, random PRs were changing the whole manual when they ran the script to regenerate docs[1][2]. Here I've changed the manual to use a consistent version of pandoc — the one from the latest release tag, which will avoid this problem in future. This will avoid this problem in future. The only time we'll need to worry about pandoc output changes is when we bump the version used in this script. I also considered using the version from the current Nixpkgs branch, but decided against it as it's unlikely that e.g. the person bumping Pandoc will remember to regenerate the manual. [1]: NixOS#162550 [2]: NixOS#168535
There was a problem hiding this comment.
Sounds good, the pandoc in the tag should already contain all of our relevant patches (the patch in b0c6127 is only needed for going in the other direction). And we can always replace the tag with a commit when we want to update it.
|
I like the idea of this and I can understand why we'd want this but who will remember to update the channel here when 21.11 goes EOL? |
What about using pandoc from the current git checkout? The only problem would be if pandoc is broken for reasons unrelated the current PR, but that should be sorted out by rebasing once the problem is fixed. |
There was a problem hiding this comment.
looks good. maybe pandoc aging as this script isn't touched much any more will add to the motivation to move the docs to markdown :) if it doesn't then at least the manual build isn't particularly sensitive, so not getting pandoc updates for a bit shouldn't actually hurt anyone
From the PR body:
This would not have prevented the problems seen today. |
EOL is irrelevant, because this is a tag, not a channel. It went EOL as soon as the first commit was made on top of the tag. The point is that it doesn't matter if it's out of date, as long as it generates the correct output. If we're missing something from a new pandoc, we can bump it. Security issues, etc. are irrelevant because the content of the repository (i.e. pandoc's input) is already trusted by any Nixpkgs user.
What is your proposed alternative? |
|
I have no real suggestion tbh. Something that would be nice (but I don't know if there would be any other consumers) could be to define something like Also, to make my statements more clear: While I don't like this PR 100%, I don't want to block it from being merged. As you said, it's not relevant to have the newest pandoc version for building the manual, I also want to prevent nixpkgs from being pinned and kept at an old release because changes tend to stack up over multiple releases and switching 4 releases or so in one commit is a lot more painful than going with every release and only fixing the small issues that pop up. |
Would it be possible to use that in a nix-shell shebang? I'd be surprised, but don't feel confident enough to categorically say it wouldn't be… |
|
Doesn't look like it (or I'm holding it wrong) :( |
Description of changes
Until now, this script has used the version of pandoc from unstable.
This means that running the script on the same version of Nixpkgs
could produce different results, and meant that when Pandoc's output
was changed, random PRs were changing the whole manual when they ran
the script to regenerate docs. 1 2
Here I've changed the manual to use a consistent version of pandoc —
the one from the latest release tag, which will avoid this problem in
future. This will avoid this problem in future. The only time we'll
need to worry about pandoc output changes is when we bump the version
used in this script.
I also considered using the version from the current Nixpkgs branch,
but decided against it as it's unlikely that e.g. the person bumping
Pandoc will remember to regenerate the manual.
Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)nixos/doc/manual/md-to-db.shto update generated release notes