maintainers: document expectations

[zimbatm]

Motivated by https://discourse.nixos.org/t/where-did-you-get-stuck-in-the-nix-ecosystem-tell-me-your-story

Address the uncertainty around maintainers by defining what it
means, what are the expectations and power you get.

Note to reviewers: some of the numbers are arbitrary and I expect would be tuned by experience.

Are there areas or cases that you think should be covered that I missed?

Description of changes

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 23.11 Release Notes (or backporting 23.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

[andir]

I like the proposal. I don't like the fixed time frames as there might be packages that don't need changes every three months or so.. I'd love to see the timeframes phrased a bit more relaxed.

[7c6f434c]

Maybe measure the time in terms of lack of reaction to specific reports of regressions or significant upstream updates?

[Janik-Haag]

We could write a script checking if a package is outdated for $timeframe based on repology data and if it doesn't get updated in $timeframe mark it as unmaintained. I already thought about that a bit.

[andir]

We could write a script checking if a package is outdated for $timeframe based on repology data and if it doesn't get updated in $timeframe mark it as unmaintained. I already thought about that a bit.

I'd not go that far. For this PR we should only try to formalize a formal understanding of the role & the responsibilities and not discuss technical solutions for (arguably) social issues.

[Janik-Haag]

I'd not go that far. For this PR we should only try to formalize a formal understanding of the role & the responsibilities and not discuss technical solutions for (arguably) social issues.

I'm fine with that but then we should probably make the timeframe less specific for example writing something like package updates should be performed in a timely manner. I think the issue in this case is not just social since there are other reasons for people to not update stuff like f.e. death so some kind of automation that sends a ping after $months seems like a sensible thing.

[zimbatm]

Relaxed the wording a little bit so the 3 months are in relation to package-related notifications. If the package is stable it won't generate any notifications (upgrades / issues / ...) and the maintainer would stay on board.

[RaitoBezarius]

This is very cool, thank you so much!

[RaitoBezarius]

I would add a mention for packages that are not affected by the "one week" rule, that is: "code owned" packages which have a large reverse dependency tree, e.g. systemd, LLVM, etc.

I don't think it's easy to put an amount of time, I'd state it as:

Committers should reach out to the active code owners and discuss the timing for a potential merge, in the event where no active code owner can be reached in a reasonable amount of time (i.e. taking into account potential holidays), merge can be performed nevertheless with a provided rationale.

The idea is to:

(1) ensure that no stray committer merges a systemd change while not being in touch with active code owner of e.g. systemd which may have extra context on ongoing changes (internal information, etc.)

(2) ensure that abandoned "important dependencies" can be slowly picked up by new committers who will garden them and find a new maintenance story for them hopefully, e.g. LLVM

Tiny version bumps and security updates could not be totally exception here, I don't have a strong opinion on that, I know that systemd security updates can lead to breakage, we had e2fs tooling's tiny version bumps breaking bootloaders (something something XFS), etc. It's a very hard problem in general.

[Ma27]

Tiny version bumps and security updates could not be totally exception here, I don't have a strong opinion on that, I know that systemd security updates can lead to breakage, we had e2fs tooling's tiny version bumps breaking bootloaders (something something XFS), etc. It's a very hard problem in general.

Would it make sense to make an exception for security updates / fixes earlier if e.g. the security team is involved as reviewer?

Generally I think that case of e.g. important bugfixes (e.g. $bump fixes data loss on runtime) or security fixes it should be possible for a committer to decide on a case-by-case basis what's best. @RaitoBezarius has brought some great examples on why I doubt that it's possible to find a general rule for this.

Also, such a ruling would exclude all those cases where the sole motivation of a person not maintaining the package in question is e.g. "wants to have the latest version available, immediately".

[fricklerhandwerk]

Agreed with @RaitoBezarius on specifying timing, or rather pushing that responsibility to maintainers themselves. Maybe we could establish a convention where maintainers are supposed to communicate what they can deal with.

That information could also be used to judge if someone is inactive.

[zimbatm]

Can you look at c67b737 and tell me if that is good enough? I'm keeping the text short so people are more likely to read it. And therefor try to not overload with exceptions.

[zimbatm]

We also need better annotations on the meta attributes for the maintainers to communicate some of these aspects to the other committers. Specifically, maintainers should list the architectures they are willing to maintain. But that's for another PR.

[RaitoBezarius]

Interesting point @ architectures they are willing to maintain.

[RaitoBezarius]

I opened #251008 for exploring the question, feel free to carry the conversation there.

[JulienMalka]

I like this proposal, thank you!

[Shawn8901]

I like it. 👍

[infinisil]

I wish we had better automation for this kind of thing, but documenting this (and adding some rough timings) is already an improvement!

Let's include the suggestion from #250344 (comment) though, I'll merge it after that.

[Ma27]

I assume that "no reaction at all" is meant here, correct? I.e. this isn't done on a per-package basis (otherwise one could lose the status if a fellow maintainer is always faster and you don't have anything to add most of the time).

When I first read this paragraph, I wasn't sure, so perhaps this should be rephrased a bit to make this clearer.

Also, we'd to give people who are about to lose their status a heads-up, correct? I guess this should be mentioned here as well :)

[7c6f434c]

Well, this is a non-pressing change to a package one is a maintainer of, and I guess «wait a week or a bit more for maintainer reaction» should be treated as «maintainer in question» in this case…

[zimbatm]

Removing a maintainer requires making a PR so that that person would be notified. But I'll add a paragraph for that.

I still think the test should be per package. Some people are active in some areas of nixpkgs, and have abandoned other parts that they don't care about anymore.

Worst case you can react on the removal PR.

[zimbatm]

10e3f2c

[7c6f434c]

Yes, pretty sure I have completely forgotten about some packages I have maintained back when I used them…

[7c6f434c]

Strictly speaking, this does not make an exception for a non-committer-maintainer approved changes. Maybe it would be better writing to say it?

[zimbatm]

Can you expand on what you mean? I'm not sure to understand

[7c6f434c]

«By default, we expect committers to wait at least a week before merging changes on packages they are not maintaining.» — however, we do not currently wait to give all maintainers time to comment, if one non-committer maintainer asks to merge, this is currently supposed to be good enough when the committer also likes the change.

[zimbatm]

I also realize we don't describe how conflict resolution happens in case multiple maintainers of the same package disagree.

[zimbatm]

I believe this PR to be in good shape, with the eventual typos. Please take another look.

[ajs124]

Does that mean the endorsement of one maintainer is enough? What if a package has multiple maintainers? What if they disagree?

[zimbatm]

I don't know if I'm ready to open that rabbit hole. For now, I suggest leaving that unspecified.

[RaitoBezarius]

IMHO, conflict resolution is 2 or 3 magnitudes harder than anything those PRs are doing so far, I would +1 not going into that rabbit hole.

[7c6f434c]

I think putting a specific duration on «wait for some maintainer reaction» is good, and everything further is reliant on judgement calls that are hard to predefine. We don't ask to definitely merge once there is a single maintainer approval, after all!

[ajs124]

Alright, then lets postpone this. It's just something I'm regularly asking myself when trying to decide if I should just merge something or if maybe I should wait.

[7c6f434c]

I guess for me the correct question will now be «will I be sincere or hypocritical saying ‘Sorry, after a single maintainer approval I did not understand this is going to be controversial’?».

[SuperSandro2000]

Can we have some tooling to get reminded of that time?

[RaitoBezarius]

I do not want to be mean, but calendars are pretty good for this.

[7c6f434c]

(Actually, no, they are not, for multiple reasons: they are hard to set up to get exactly the relevant notifications for this batch when you cut out some time to look at Nixpkgs, and most of them don't integrate well enough with browsing the pull request.

On the other hand, an option for CI re-requesting reviews in case there is a check you want to let finish is useful in any case, and if it exists, maybe remind-me-in-a-week would be doable on top of that.

So the need is real, but not decision changing for this PR.)

[zimbatm]

I agree; we need some more tooling for this.

[AndersonTorres]

Also, I suggest something about reading the manuals.

[zimbatm]

I'm sorry, but this last review is expanding the scope of the PR. This is exactly how PRs die; because reviewers keep asking for more stuff until the contributor gets exhausted.

Before submitting reviews please ask yourself; Is this a unit of work that is consistent and that improves on the existing situation? If yes then let's merge this and start gathering real-world data from it. I'm sure more PRs will follow afterwards.

[FRidh]

Looks good to me.

[zimbatm]

Alright, this is ready. Unless anything new comes up, I'll merge it in a few days.