maintainers: require GitHub handle (documentation)

[wolfgangwalther]

This documents the requirement for a github and githubId fields in maintainer handles. It does explicitly not enforce this requirement, yet, becaue there are still some maintainers without.

Enforcment via tests/CI will happen in a separate step, see #437085.

Please keep the discussion in this PR about the specific wording of the changes. Any discussion about "should we do this at all", is better done in #437085, where it was already started. We don't want to split this discussion among different PRs. Any such comment will be marked as "off-topic" here.

From the big numbers of approvals in #273220 and #437085, I conclude that we do want to do this. This PR follows up on what has essentially already been decided by the community, but has been blocked so far in implementation due to existing maintainer entries.

Things done

• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

---

Add a 👍 reaction to pull requests you find important.

[Sigmanificient]

@wolfgangwalther Thanks for all you work on maintainers!

[SigmaSquadron]

our entire CI hinges on wolfgang's maintenance

[wolfgangwalther]

Thanks for the feedback everyone. That's enough approvals for me to get this merged.

[MattSturgeon]

I believe we also have some contributing docs that explicitly state a GitHub account is not required (to be a maintainer? contributor? I can't recall). If we're now enforcing that the attribute is set, we should rephrase that to avoid confusion.
-- #437085 (review)

The note I was thinking of was:

nixpkgs/CONTRIBUTING.md

Lines 6 to 7 in 422a2b5

	A GitHub account is recommended, which you can sign up for [here](https://github.com/signup).
	See [here](https://discourse.nixos.org/t/about-the-patches-category/477) for how to contribute without a GitHub account.

...From the start of CONTRIBUTING.md.

That's still correct, even after this and #437085; you don't need to be a maintainer to contribute. Although, I wonder if it should now have a caveat, for clarity?

Regardless, that's tangential. This PR is about the maintainer docs, not contributing in general.

[wolfgangwalther]

That's still correct, even after this and #437085; you don't need to be a maintainer to contribute. Although, I wonder if it should now have a caveat, for clarity?

I see what you mean. I think it would not actually help clarity if we mentioned the fact that you need a github account to be a maintainer. That's because at this stage, for the very first contribution, you don't even know what a maintainer is. If you're really in the situation that you don't want / have a github account, reading up on the maintainer thing might lead you to believe that you couldn't propose the addition of a new package. But that's not true, you could do that, somebody else would just have to commit to maintaining it (and opening the actual PR). Thus.. I'd say it's probably more confusing than helpful to mention it there, at least that's how I feel.

[MattSturgeon]

That's because at this stage, for the very first contribution, you don't even know what a maintainer is. [...] I'd say it's probably more confusing than helpful to mention it there, at least that's how I feel.

I can get on board with this perspective. I see how a caveat could be more confusing than helpful, especially for someone still fuzzy on "maintainer" vs "contributor".

A counter argument might be that CONTRIBUTING.md (etc) is not just for first time contributors; I suspect that in practice is is more often used as a reference guide rather than a "first PR" tutorial.

I think you could refute my argument by saying that, regardless of how it is actually used in practice, it is written for new contributors.

[zeuner]

That's still correct, even after this and #437085; you don't need to be a maintainer to contribute. Although, I wonder if it should now have a caveat, for clarity?

Currently, serious contribution is more or less impossible when being barred from maintainer rights. Without a corresponding clarification in the documentation, committers are likely to refuse PRs involving new packages just because there is no maintainer entry in meta. However, the technically optimal solution for a contribution can involve new packages.

One example would be the unrolling of git sources involving submodules in order to improve source fetching. Putting all the necessary logic into the package which includes such a git repository is inferior with respect to maintenance and code reuse, so a better solution is to put it into a separate package that can be used by other packages. In this case, @GaetanLepage split the contribution it out into a separate package and generously took the maintenance responsibility. However, this cannot possibly be expected for every contribution, and for the resulting git-unroll package, gm6k would be a perfectly reasonable addition to the maintainer entry due to upstream authorship.

Another example are the link paths in alsa-lib plugins. A clean and robust solution to related issues is a wrapper package that provides binaries with corrected link paths, alsa-lib-with-plugins, which in turn is currently only possible with a maintainer entry. Without the wrapper package, it was necessary to set the link paths from the calling environment, which is tedious for reverse dependencies with executables, and close unfeasible if the reverse dependencies provide shared libraries.

In both exemplary cases, limiting contribution to what is possible without adding new packages leads to obvious quality defects. Therefore, I would argue that contributing without maintaining is a rather artificial idea, not really congruent with real life needs.