maintainers: require GitHub handle (documentation) (#437469)

Author: wolfgangwalther

maintainers/README.md

@@ -119,9 +119,8 @@ When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the followi
 
   Note: GitHub's "Verified" label does not display the user's full key fingerprint, and should not be used for validating the key matches.
 
-- If the user has specified a `github` account name, ensure they have also specified a `githubId` and verify the two match.
+- Ensure that the user has specified a `github` account name and a `githubId` and verify the two match.
 
-  Maintainer entries that include a `github` field must also include their `githubId`.
   People can and do change their GitHub name frequently, and the ID is used as the official and stable identity of the maintainer.
 
   Given a maintainer entry like this:
@@ -139,7 +138,7 @@ When adding users to [`maintainer-list.nix`](./maintainer-list.nix), the followi
 
   First, make sure that the listed GitHub handle matches the author of the commit.
 
-  Then, visit the URL `https://api.github.com/users/ghost` and validate that the `id` field matches the provided `githubId`.
+  Then, visit the URL `https://api.github.com/user/10137` and validate that the `login` field matches the provided `github` handle.
 
 ### Maintainer teams
 

maintainers/maintainer-list.nix

@@ -4,13 +4,12 @@
    handle = {
      # Required
      name = "Your name";
-
-     # Optional, but at least one of email, matrix or githubId must be given
-     email = "address@example.org";
-     matrix = "@user:example.org";
      github = "GithubUsername";
      githubId = your-github-id;
 
+     # Optional
+     email = "address@example.org";
+     matrix = "@user:example.org";
      keys = [{
        fingerprint = "AAAA BBBB CCCC DDDD EEEE  FFFF 0000 1111 2222 3333";
      }];
@@ -21,16 +20,16 @@
 
    - `handle` is the handle you are going to use in nixpkgs expressions,
    - `name` is a name that people would know and recognize you by,
-   - `email` is your maintainer email address,
-   - `matrix` is your Matrix user ID,
    - `github` is your GitHub handle (as it appears in the URL of your profile page, `https://github.com/<userhandle>`),
    - `githubId` is your GitHub user ID, which can be found at `https://api.github.com/users/<userhandle>`,
+   - `email` is your maintainer email address,
+   - `matrix` is your Matrix user ID,
    - `keys` is a list of your PGP/GPG key fingerprints.
 
-   Specifying a GitHub account ensures that you automatically:
-   - get invited to the @NixOS/nixpkgs-maintainers team ;
-   - once you are part of the @NixOS org, OfBorg will request you review
-     pull requests that modify a package for which you are a maintainer.
+   Specifying a GitHub account is required, because:
+   - you will get invited to the @NixOS/nixpkgs-maintainers team;
+   - once you are part of the @NixOS org, you can be requested for review;
+   - once you can be requested for review, CI will request you review pull requests that modify a package for which you are a maintainer.
 
    `handle == github` is strongly preferred whenever `github` is an acceptable attribute name and is short and convenient.