2023-12-21 Documentation team meeting notes #101

Development Documentation
1

Notes

doc: add more details on testers.testVersion by DanielSidhion · Pull Request #275585 · NixOS/nixpkgs · GitHub

  • Merged
  • More linting?
    • Testing code snippets automatically would be great,
    • would force authors to make examples that work
  • Would still be useful to run the examples manually for now to make sure they work
    • Though hard to do without more context

doc: diagram explaining what it means for a dependency to be propagated by bzm3r · Pull Request #271797 · NixOS/nixpkgs · GitHub (author: bzm3r; notes by: bzm3r)

Summary of the situation so far

I (bzm3r) was confused by the following sentence (manual section for stdenv): .

A dependency is said to be propagated when some of its other-transitive (non-immediate) downstream dependencies also need it as an immediate dependency. 3

To help me understand the existing language in the manual, I drew a diagram following the language carefully; it confirmed what I guessed it was trying to say.

I decided to upstream the diagram, as a low-effort PR (“might as well, the work is already done”).

  • conceptual intent: diagram to quickly confirm for the reader what they might be guessing is being said, and if not, to give them another hint.

Discussion around the diagram was simultaneously englightening and confusing.

Including the diagram is no longer a low effort PR, my motivation for it has dropped significantly as it stands. I would prefer to:

  1. include the code snippet suggested by @infinisil
  2. include a version of the diagram that matches the code snippet provided by @infinisil (but only because people seem to want it, not because I care for it in the slightest; see detailed discussion)
  3. expand manual sentence that began this all into a pargraph:
    • eleminate the footnote, make it the second sentence
    • add sentences describing:
      • when propagation cannot be avoided
      • how @Ericson2314’s comment (see detailed discussion) can be “realized” moving forward in future derivations (Maybe by explicitly override any possible shared dependencies in nixpkgs?)
      • discourage propagation in general, except as yet another regrettable historical consideration
  4. (Eliminating historical baggage part 1) Create an issue to eliminate propagation entirely

Future work: Create an issue asking how we can eliminate unnecessary complexity around target/host/build that the manual alludes to. Create issues for every single thing in the manual that is described as unfortunate historical baggage. (e.g. )

Results

Worked together on the PR, removing the diagram, but including the example code and clarifying the explanation.

Merged!

Misc

Merry Christmas! :christmas_tree:

1 Like