You raise a number of valid points. Unfortunately, there’s no set requirements yet about acceptable criteria in a PR. There’s the RFC for defining a PR workflow, however, I think that suffered from trying to be too opinionated about the implementation and failed to be ratified. There was also a previous issue https://github.com/NixOS/nixpkgs/issues/11166 .
In our current process, communicating standards through PR reviews doesn’t really scale well, it takes a lot of time scan the changes, type a response, then iterate. This time investment often disallows me from getting to PRs which may be in a “ready-to-merge” state, I just didn’t have the free time to get around to them (I currently have 300 github notifications, and get 20-120 a day).
To help scale with community growth, I started making some videos:
I received some new recording gear, when I have some free time and the desire to record again, I’ll probably make more “polished” videos. Having the keyboard clack in the background is very distracting. Also having to type + think + talk isn’t the easiest thing todo, so I’ll probably change it so that I do the final voice edit after the screencast has been recorded.
But seeing as some of the videos have 800+ views, I’m assuming that some people find the scenario-specific videos valuable. And maybe having some polished: ‘Getting started’, ‘Using NixOS’, ‘Using nixpkgs’, ‘Contributing to Nixpkgs’, ‘How to do
<language> packaging in Nix’. Would go a long way for people to “learn” about the best practices. If they are of sufficient quality, maybe we can make them semi-official at least make a reference to them from the official docs.
Documentation and resources scale well, however, NixOS/Nixpkgs documentation suffers from three different issues: discoverability, relevance, and death-by-details.
Discoverability: I didn’t even know that Nixpkgs had it’s own manual til after I became a committer. There’s https://github.com/nix-community/awesome-nix which is helpful, but I only new of it after i was added to the NixOS organization and had a PR opened against it.
Relevance: Most ecosystems have a nice “system of effects” when people have issues, there’s usually some stack-overlow, blog posts, or similar issues in github. Generally all I find are github issues, and hopefully this will be less of an issue in the future.
Death-by-details: We generally send people over to
nix-pills to get their feet wet with nixpkgs. However,
nix-pills goes through the process of essentially creating a stdenv which is way more than someone probably cares for if they are coming from a, “read an article about nixpkgs and just wanted to test drive it in this repo of mine”. It reminds of trying to learn haskell, where I just wanted to know how to “read from stdin”, but found myself hours later reading about Monads and category theory. I just wanted to read in a number.
EDIT: the revamp to the homepage I think helped with the discoverability. There’s now a “Learn” tab on https://nixos.org/