docs: expand explanation of patchShebangs hook

[fricklerhandwerk]

• clarify motivation and mechanism
• explain usage
• add interlinks
• add links to sources to enable research

based on https://discourse.nixos.org/t/what-is-the-patchshebangs-command-in-nix-build-expressions/12656

I haven't yet decided if adding source links to the manual is a good idea and haven't found any discussion on the topic.

• Pro: Easy entry point for research
• Con: Will point to old commits eventually

Would be cool if we had a preprocessor that converts references to /path/to/file:L123-L456 in the current repository into GitHub links, but keeping it consistent with changing code would be a can of worms on its own.

Opinions?

Closes #129741

Motivation for this change

Things done

• Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
• Built on platform(s)
  • NixOS
  • macOS
  • other Linux distributions
• Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
• Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
• Tested execution of all binary files (usually in ./result/bin/)
• Determined the impact on package closure size (by running nix path-info -S before and after)
• Ensured that relevant documentation is up to date
• Fits CONTRIBUTING.md.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/what-is-the-patchshebangs-command-in-nix-build-expressions/12656/11

[jtojnar]

Looks great, few minor comments.

[fricklerhandwerk]

@jtojnar Thanks for the precise observations, corrected.

[fricklerhandwerk]

Anyone wants to merge this?

[siraben]

LGTM, but please resolve the merge conflict.

[siraben]

udocker commits here?

[fricklerhandwerk]

Random stuff from rebasing, I don't know...

[fricklerhandwerk]

@SuperSandro2000 @jtojnar Can we finish the discussion on using source links and merge this? I hope having links in the first place is undisputed, as it helps people diving into the code, and the code is the definition of how things work.

Calling @Ericson2314 because we looked at the PR together.

Some considerations, leading me to conclude that permalinks are the better option:

Pros:

• permalinks do not break
• maintenance is optional
• correctness within documentation ensured without additional cost

Con: (same as for all prose documentation)

• correctness w.r.t. release version may decay
• have to be updated manually
  • hopefully by avid boyscout-y readers who notice a reference is old...

One could add an item to the release checklist, to go through permalinks and update them to the latest pre-release revision. That may in fact encourage people to actually look at the docs now and then and see if they still make sense. @tomberek what do you think?

Using links to release branches or master...
Pro:

• points to most recent version
• may be fairly stable for many things (but we don't know)

Con:

• will break eventually
• must be maintained to keep correctness

[Ericson2314]

@fricklerhandwerk I would prefer master, because the manual should document the version of the code it itself came from! (In general, with monorepos, there is a tendency to hit issues where the mono repo in affect refers to / depends on prior versions of itself, and I think that is no good!)

The maintenance burden is very real, however, and I don't want to sweap that under the rug. It's a lot of up-front the work, but I think the answer is doing a (very!) technical solution for this:

• The links are written without reference to github or any branch, in a custom URI syntax of our choosing.
• Next to the docs are snippits of what we expect those links to point to. Maybe they are named with the URI for easy lookup.

As part of the docs build:

• A linter that can understand those URLs checks that the text snippit matches the URL
• A pass on the markdown turns our custom URI into a github URL referring to the right branch (master for unstable docs, release-* for stable docs, etc.)

We thus ensure the docs are in sync with no manual auditing effort, and as a bonus make the release process easier (no need to update the URLs, keep them updated with backports, etc.). Bonus, in addition to links we can have the same method for code snippets that render in the docs too!

This is a lot of work, but I think it is extremely valuable, as it would allow us to document Nixpkgs with far, far more textual references in a way is sustainable with respect to human effort and avoiding the damage of false out of date documentation (arguably worse that no docs at all!)

[fricklerhandwerk]

I would prefer master, because the manual should document the version of the code it itself came from!

Agreed.

In general, with monorepos, there is a tendency to hit issues where the mono repo in affect refers to / depends on prior versions of itself

Which kind of issues do you mean exactly? I find it hard to imagine if those references are immutable and persistent.

It's a lot of up-front the work

Yes, and it sounds conceptually awfully complicated for throwing in a few links to the code. One much simpler automation I could agree on would be to compare the contents[1] at the tip of the branch in question to contents behind the permalink, update the link if there was no change, and throw a build error otherwise to force maintainers to check for semantic consistency. I don’t know whether already or how we tell the build which branch we are currently on, though. In any case this is optional and independent of this change right now. Nonetheless I find it too expensive to be worthwhile, as my impression is that people rather iterate over small parts incrementally, such that we can expect some manual care to be exercised. We can reconsider if someone who actually does the work (or convincingly claims to be prevented to do that work as things are) would significantly benefit from automation. [1]: Exact contents for line references (usually preferable anyway), existing file for file references. The latter as in „the implementation can be found in `foo.nix`“.

avoiding the damage of false out of date documentation (arguably worse that no docs at all!)

What is the argument here? Some parts of the docs seem to be stale or confusing, and I’m not convinced this is worse than not having them. Disagree on the term damage, since the PR in question appears to me a niche topic. Also see my argument that permalinks stay consistent with prose by default. Semantic code changes would already require prose change. Someone implementing that prose change may as well check how recent the links are and whether they point to something appropriate. Review is also involved in this kind of sanity check.

[jtojnar]

I prefer permalinks precisely for the reasons you outlined. As someone who writes docs, the consideration what to do when a link is outdated is most important to me:

• for master link, I need to find out when the part of manual containing the link was changed, find Nixpkgs commit which master pointed to at that time, look at the link contents and then find the corresponding new place. And I am not even mentioning how to find if the link is incorrect.
• for permalink, I can simply compare it with master and when the lines the links point to differ, I can look for the old contents (either in tree or in git log -p).

Yes, a new linking scheme such as the one John would resolve this more elegantly. But it is significantly more work than just using the permalink, even though it is essentially the same solution. The main difference is that the new scheme would store the snippet as a part of a link, whereas the permalink scheme stores the snippet in the link target. Yes, the former would allow for more flexibility (e.g. using regexes) but again, I am not sure it is worth the effort.

---

And yes, all of those are at least partially automatable but until we have such automatization, the permalinks make most sense to me, as mentioned above.

[Ericson2314]

Yeah. Links to files from specific commits are fine to start. Maybe we can accumulate a few of those and then the case for the automation will build up over time.

[fricklerhandwerk]

@jtojnar @Ericson2314 updated to permalinks. Ready to merge?

[jtojnar]

Maybe link to the place that actually does that instead, since people might click the link and be confused.

[jtojnar]

Maybe move this to the beginning to serve as an overview.

[fricklerhandwerk]

@jtojnar Thanks for the hints, incorporated some. Though in general I would like reviewers to tell what must be changed to meet agreed-upon quality standards, not what could be changed because it's nice to have. This PR is already over a year old. We can always slightly improve later if it appears important enough.

[roberth]

Let's merge this soon.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-34/20901/1