I have three questions regarding documentation and pinning nixpkgs.
I wonder how the examples should be use refer to nixpkgs.
nix.dev declares that <…> is a anti-pattern.
I think this makes sense in the context of the statement.
But examples should be also concise, so I prefer nixpkgs = <nixpkgs>.
Where we should put single entry in the “reference” section on nix.dev: Pinning Nixpkgs — nix.dev documentation
I think its not really a reference but useful information that could be extended maybe even into a tutorial, anyone who disagrees on this direction?
Good question, and I would also like to see a compelling answer (and would be happy if you elaborated one given you find it important enough to spend time with), but it’s not high priority: we have many other things where spending effort has much more impact. One example being delivering a good overview on the situation and trade-off we have with adopting flakes. Details like these are important as well though, so (again, if you care enough) open a pull request with a suggestion for an answer and reasoning good enough to preempt bikeshedding. An issue to lead a discussion might grab more attention than it’s worth.
If you mean where to put such an answer - I’d say it depends on the format. If we go by The Documentation System, we have as options: tutorial, guide, explanation, and reference.
Reference belongs to the manual, and I would not object moving that section out of nix.dev and finding a spot in the manual. Telling how to do it best would be something for a guide or a collection of brief encodings of best practices or antipatterns on nix.dev, referencing manual. Not sure what a tutorial looks like, but we haven’t really defined a place for explanations yet, where in this case I would imagine explaining why the different options even exist and some reasoning why to use one or another. Having such a write-up is certainly valuable, and having a deterministic place to put and find them would be great. I made a proposal to have an „optional“ section in the guide structure, but I’m open to suggestions.
maybe 22.05 is based on nixpkgs-unstable branch, while nixos-22.05 is based on nixos-unstable? if you’re using that for a nixos system, then go with nixos-22.05, if not then guess you can go with 22.05.
and i would recommend using flakes instead of that non-flake way because flake is a way better workflow when it comes to pinning, managing dependencies/inputs on other nix repositories.
Because examples should be simple they should not break on any system that is stable so should be good enough, concise and should cause little traffic to download packages.
I was on unstable until 22.05, I never had problems with a broken (base) system on either.
More complicated examples like the current example from nix.dev actually need pinning, so they should be pinned.
In the context of my guide It’s enough to clarify this at the beginning and link to the “pinning reference”.
I keep a note for myself that the “pinning reference” needs some work.
Documenting flakes is a task that seem to be endlessly expandable .
i mean it is obvious from that perspective, but having a nixos prefix or not makes a difference in how they are tested, or include one thing or another. i don’t think anything not prefixed with nixos include nixos specific stuff like some nixos specific tests.
do you know from which branches do they base these branches on? nixos-unstable and nixpkgs-unstable?
Individual PRs are cherry picked into the release-* branches.
Hydra constantly builds current tip of active release-* and master branches. If this build succeeds relevant commits again are cherry picked into nixos-* branches. (This last step is overlay simplified for the matter of this post)
There should be answers on this in the maintainer section of the contributor guidelines, but there are not. The closest thing is maybe commit policy. @yuu would be great if you could seize the opportunity to encode what you find and learn right into the manual. @jonringer I remember there was a GitHub issue or something like that from last year or so where you roughly outlined the process, do you have a pointer?
.