My experience of contributing to Nixpkgs

Meta
1

Nixpkgs is an interesting beast. It is massive and sprawling. The barrier to entry to contributing is quite low compared to many distros, just open a PR on GitHub. I drive multiple NixOS machines every day at work and home. I also contribute to Nixpkgs quite frequently. I review PRs, add packages, clean packages up, remove packages, add new tooling, and so on. Nearly every day.

The experience of contributing to Nixpkgs is probably most like Sisyphus pushing his boulder. Once you open a PR, it is up to you to get anyone to look at it. Beg. Plead. Bargain. Scream. I don’t know. Getting anyone to even glance at a PR is a task that is the first hurdle. And it is truly one of the hardest.

Nixpkgs has zero systems for ensuring anyone actually looks at PRs, nor any incentives at all to do even do so. If someone does it is because of luck, your PR is an “easy one”, or because it aligns with someone else’s goals. There are about 5 people who regularly look at PRs from the unwashed masses. Sandro is the most obvious one, and most likely one to look at a given PR. It is truly thankless work.

There are several issues with this.

  1. Very few people actually look at PRs, this is quite obvious if you’ve spent time here. “Very few” is relative to the number of maintainers.
  2. If a PR is not an “easy one”, good luck getting nearly anyone to look at it. Easy is: updating a version & hash, or adding a new package. If you add a new Nix function, modify one, touch any Bash GOOD LUCK.

I have experienced this many times. You just have to beg, and beg, and beg, and beg, and beg, and beg, and beg, and beg, and beg, and beg, and beg for someone to look at your PR. For months, or even years! Then someone will come along, say “you misspelled the word ‘attribute’,” or “that doesn’t match how I would do it,“ and there it is. Your review. Nothing of substance said about the content.

Ok so you begged for a few months, and someone reviewed your PR. Congrats. What’s next? Well next is getting it merged. This is the other barrier. Nixpkgs has this funny system where the final say on a PR is often up to “committers.” This is a group of people whom have been deemed “the best of Nixpkgs maintainers.” And are allowed to dictate what goes in. I hope you haven’t gotten tired of begging. Get on your knees and make sure they hear you! If a committer requests a change, good luck getting it merged. The nominal policy is “no reviews are blocking reviews,” but I’ve not seen a single instance where that was followed.

Committers are an in-group that get to decide which nitpick you get today. “Your function name is not what I would’ve written,” “I think there’s a better way to do this [I will not tell you].” And also you get a single review every few weeks. That addresses one thing. Then another review about a completely separate thing the next month. Why not all at once? Well committers are too busy to interact with you. Or something. I’m sure it’s important. I do recommend looking at what the average committer actually does, it is quite interesting. The best way to get their attention is to do something with their pet project. But almost many of them just self-merge their own PRs and not much else. Maybe merge a fellow maintainer’s PR on a package they maintain. A large amount of Nixpkgs processes are contingent upon committers actually looking at PRs, yet it is very similar to pulling fingernails to actually get that to happen. If you were to ask me how many committers there were, I would guess like 30-50. Instead there’s over 200. What are they doing? I’m sure its too important to give time to look at the PRs people have written. Or at least I hope it is, since that is what they have shown is the case, regardless of what is said.

This is not necessarily their fault, as annoying as it is. Nixpkgs is a volunteer project and you cannot force people to do so. But there is also negative incentive for any other above to occur. Why review anything when you can just not? Why merge anything when you can just not? There’s absolutely no reason some Jane Commit should every look at anyones’ PR. In fact it sounds quite annoying to do so when she has been at work all day. Luckily to keep her commit bit all she has to do is merge one PR a year. So she merges an update for a tool she uses at work. “Great, I did my part for the year. See you next.”

Taking a good look at projects that are quite nice to contribute to, what do they do? They have accountability and responsibility for PRs. Nixpkgs already has some in terms of meta.maintainers. How to make someone feel accountable or responsible for PRs from the peanut gallery? Take a good look at the Rust Project.

And then there’s just the attitude. I’m not going to call the moderators every time someone is rude to me, that’s a waste of everyone’s time. But wow. I spent hours building something to try and make a process easier. But sorry for wasting your time for asking you to look at it.

Overall I really want to help Nixpkgs. I think it’s a really cool project. But what is the point of doing anything for Nixpkgs if it is just a stalled PR generator. “Oops your PR went over the limit, and is now deemed to be too hard since I cannot click on it, scan it, and say ‘well that looks right.’ You are now sentenced to six months of begging.” What a nice experience I really wish everyone had the chance to live it.

20 Likes
2

I share your pain in docs: add AGENTS.md and symlink CLAUDE.md by fzakaria ¡ Pull Request #534657 ¡ NixOS/nixpkgs ¡ GitHub

1 new file to just ask AI agents to read CONTRIBUTING.md.
No changes to the file otherwise to bike-shed about… and yet impossible to merge :upside_down_face:

Such is life.

5 Likes
3

I’m hoping to write a more thorough reply tomorrow, but I’d kindly ask to refrain from hijacking this topic for the ongoing AI push. This has its own topics already, no need to continue here.

26 Likes
4

Thanks for writing this up. I agree with the points raised here.

My commit bit was removed after around 10+ years of contributing, and now I often have to plead to get things merged even for packages I maintain. That has made the problem much more visible to me: without a clear path from “this PR is ready” to “this PR can be merged,” contributors end up depending on personal attention, persistence, and luck.

For what it’s worth, I also tried raising this with the Steering Committee, but I have not received an answer after a year.

I think a lot of this could be improved with better automation and, these days, AI-assisted tooling: triage, stale-state detection, reviewer routing, summarizing PRs, identifying likely maintainers, detecting whether feedback is blocking or optional, and helping move ready PRs forward. But too often review is used to police contributors rather than to reduce gatekeeping and help contributions land.

At the scale of Nixpkgs, I don’t think the current model can keep working. We need a new contribution model. Something closer in spirit to the Linux kernel, where ownership, review responsibility, subsystem boundaries, and escalation paths are clearer. Nixpkgs is too large to keep relying on contributors manually begging the right people until something happens.

10 Likes
5

LLM contributions only make the problem worse. Now there’s a sea of PRs that were not ever written or tested by a human, and you must filter them out. Being asked to review LLM PRs is honestly exhausting. Why should I read a PR that the author couldn’t be bothered to write.

Rather than adding more LLM noise, making the contribution docs better is extremely higher value. And if LLMs are so good at what it is claimed they do, this would elevate them the same.

17 Likes
6

This whole thing would be easier to take as constructive feedback if it were less hyperbolic. I’ve had a look at your PR history (I will respect your desire to make anonymous complaints in public, but I’m pretty sure I know the account you’ve been using on GitHub). Your longest-open PR was about 11 months (you closed it yourself). So unless there’s some glitch in the data (possible!), you’ve never had the experience of begging for ‘even years’.

I then tried to look for instances of repeated begging, and couldn’t find too much of that either. How are you doing this? You’re not posting on the Discourse thread (not that this is all that effective, given how people use it; but at least it’d explain to me where this is coming from). Your typical PR consists of you pinging a maintainer once or twice (by which I mean requesting a review or @-mentioning someone) before you get what you need (a review or a merge) or quit.

I think the thing you’re pointing at is worth discussing, but we should be discussing it at the scale at which it actually happens. I understand venting frustration with hyperbole but it makes it much harder to look at the situation and make reasoned decisions about what to do differently.

13 Likes
7

To an extent, I hear where you’re coming from, but I think that this is an especially cynical take on the nixpkgs system. To go over a few points:

  • It’s hard to get anyone to look at “hard” PRs

    This might not be the worst thing because it does stop people from reviewing PRs they aren’t qualified to review. Lots of very savvy people know (in my opinion) shockingly little Bash. It’s fine that those people are reviewing updates and new package additions that aren’t complicated. The same is true for new nix functions or for complicated packages in general. If any reviewers comfortable with multiple precision arithmetic are reading this, they should check out #521132, which I think is “radioactive” in the sense you’re talking about :). This is related to what you were saying about “pet projects” because if people are interested in something and know it well, I don’t think it’s necessarily bad if they spend most of their time making sure those things are actively maintained and that updates are being merged.

  • Getting merges is hard

    This is related to the bit on committers elaborated below, but I don’t necessarily mind this. Having said that, this can be one of the more frustrating parts of working on Nixpkgs. It can be very frustrating to have an approved PR that just can’t get merged. It’s also frustrating to see this happen to a good commit as a reviewer. However, I’d rather it be too hard than too easy to get merges. If anyone reading this is having similar issues, I would recommend that you go out of your way to make Nixpkgs “friends” that you can ping to look at your commits once they’ve been reviewed (most people have their emails in maintainer-list.nix :)). Actively seeking people out for reviews/merges is the way to do it, in my opinion. This also ties in to your mention of “pet projects” because I would recommend that people check out who is actively working on the sort of software they’re interested in. This is a great way to meet Nixpkgs “friends”!

  • Committers are an in-group prone to nitpicking

    With a project that uses GitHub as much as Nixpkgs does, we definitely have to be careful about who has commit access. We’re at the point now where one bad (intentionally or not) commit could ruin a lot of people’s days, including many that work at large companies. Obviously, we owe nothing to these companies, but they should be able to trust that we’re vetting every change to Nixpkgs. All that is to say that lots of “nitpicks” are often about keeping the quality of Nixpkgs as high as is reasonable. My first PR had 164 replies- mostly because I was an inexperienced contributor trying to do something well outside of my comfort zone. At the time, lots of the replies and suggestions felt like nitpicks, but I’ve come to appreciate that no one is trying to insult my work-- people just care about the quality of what we’re all using every day.

  • Accountability

    Unfortunately, this might be a side effect of the structure and increasing popularity of Nixpkgs. There’s been lots of talk lately about how to prevent “slop” PRs in Nixpkgs. Until we come up with some mechanism to stop or mitigate “slop” PRs, implementing any kind of accountability will be hard.

  • Attitude

    Toxicity has been a problem in FOSS for a long time, and I won’t defend it. The thing that’s helped me the most is to generally not take it personally (which can be very hard sometimes), but this is more of a band-aid than a cure.

I don’t want to come across as an apologist here. I appreciate that you’re taking the time to note that we all have lives outside of Nixpkgs, and I think that’s probably a driving force for a lot of the issues we’re discussing. It also sounds like you have a good bit more experience as a contributor than I do, which is worth noting. I hope I haven’t misinterpreted any of your points.

3 Likes
8

Thank you @some for your feedback–it’s something I think a lot of us go through to one degree or another.

The current solutions (such as they are) seem to be:

  • Open a PR and hope for the best
  • Open a PR and use the PR thread
  • Open a PR and find a sympathetic person (the clique thing you mentioned) to continually route through
  • Use a flake (imperfect as they are) and just don’t mention it (I suspect this is the de facto most common answer for unpackaged stuff).

I agree that this is not an ideal situation.

Things we could consider to improve the situation:

  • Find some way of having a review queue or tooling for “I have a few minutes, grab me something I can review”
  • Find some way to increase the number of folks with a commit bit (the bar is a bit high right now and we’ve lost/ejected folks who previously were helpful in this regard)
  • Open up yet another channel that’s “untrusted” or “optimistic” or whatever that proactively merges with a passing review (and then figure out how to promote PRs and figure out CI load and whatnot)
  • Revisit our processes so that signing off isn’t such a burden for folks with a commit bit

We are going to need to find a way of helping solve this as we continue growing.

5 Likes
9

To be fair, I think that you just tripped over a hornet’s nest with this one. The only thing regarding gen-AI this community can agree on is that it’s controversial. Every discussion on this topic seems to quickly become heated. 99% of PRs aren’t going to get even 1% of that much heat.

10

You do raise an excellent additional opportunity for improvement: people could be fixing the PR backlog instead of arguing about AI on Discourse.

8 Likes
11

I always try to keep in mind “what type of door” am I discussing

Some decisions are consequential and irreversible or nearly irreversible – one-way doors – and these decisions must be made methodically, carefully, slowly, with great deliberation and consultation. If you walk through and don’t like what you see on the other side, you can’t get back to where you were before. We can call these Type 1 decisions. But most decisions aren’t like that – they are changeable, reversible – they’re two-way doors. If you’ve made a suboptimal Type 2 decision, you don’t have to live with the consequences for that long. You can reopen the door and go back through. Type 2 decisions can and should be made quickly by high judgment individuals or small groups.

reference: https://s2.q4cdn.com/299287126/files/doc_financials/annual/2015-Letter-to-Shareholders.PDF

My own opinion: There is often too much discussion about two-way doors within the community.
We put too much burden on ourselves to try and have the best & correct approach the first time, when often that’s not necessary and causes lots of the pain we’ve documented here.

12 Likes
12

I like this perspective on the issue. Trying not to pull the conversation too far off topic; but, I feel like the nix community has felt flakes were a one-way door that has forever changed the ecosystem in an irreversible way. Regardless of my personal options on the feature, it has very much divided the community and caused lots of discussion because of the feature‘s incompleteness. The community as a whole doesn’t every want a repeat of that so I feel like we are very adverse to making quick decisions to our own detriment.

Coming back to the main topic, I have also struggled with the PR system. It normally takes going to the matrix channel and pinging it after a PR has sat for a week before it gets any activity. The core maintainers have an immense amount of work and it is understandable that it takes a while to get around to PRs; however, I would propose an escalation approach to PRs if it is possible. Something like if a PR has 1-2 reviews it’s prioritized at level 1 3-5 level 2 and so on. This would encourage people to review the packages they want merged to help boost their priority. It gets more eyeballs per PR and hopefully fast tracks features people want.

5 Likes
13

I mean the downside of this is that this incentivises people to approve PRs without having done any diligence.

It risks PR approval becomming the new commenting +1.

Not that I fundamentally disagree, doing an approving review as someone without commit bit feels kinda pointless sometimes.

2 Likes
14

Not even joking with the idea that we ought to add a nixpkgs-review roulette command that just gives you a random recent PR to review

11 Likes
15

Your PR got overwhelmingly rejected and you view that as a discussion to win. That’s very different from some’s experience of many contributions struggling to get attention.

4 Likes
16

This is an incredibly unkind assumption to make.

2 Likes
17

Don’t you see the irony of suggesting to not argue in discourse all day (or y’know proposing to have meritocracy in nixpkgs) while maintaining 9 packages?

Don’t get me wrong, I do not judge people by their workload, but this is a weird position to be in making claims like that.

8 Likes
18

@some you have a valid point, we should all be respectful with the time of each other. But you cannot presume that every AI assisted contribution was never reviewed. We need to improve the process! On my end, assisted with AI or not, I always try to structure a change in a way that people can follow it, I try to put myself into the shoes of someone reviewing it….

19

Would you say that you meet that standard?

20

In my opinion, we need some better tooling, that helps to ping relevant persons, when a pull request has been made. Who appropriate people are, is up to debate but some incomplete ideas are:

  • Maintainers of touched modules/packages
  • Owners of touched files
  • Maybe people, who touched the same files multiple times in the last year or so.

Maybe have a look at this discussion.

To be honest, I don’t know how feasible such a tool would be and if GitHub’s API is flexible enough.

There is still the issue to find a committer.

1 Like